doc: update doc & fix some mistakes

README.md

@@ -32,7 +32,7 @@
     <a href="https://pywebio.readthedocs.io">[Document]</a> | <a href="http://pywebio-demos.demo.wangweimin.site/">[Demos]</a>
 </p>
 
-PyWebIO提供了一系列命令式的交互函数来在浏览器上获取用户输入和进行输出，可以用于构建简单的Web应用或基于浏览器的GUI应用。
+PyWebIO提供了一系列命令式的交互函数来在浏览器上获取用户输入和进行输出，将浏览器变成了一个“富文本终端”，可以用于构建简单的Web应用或基于浏览器的GUI应用。
 PyWebIO还可以方便地整合进现有的Web服务，让你不需要编写HTML和JS代码，就可以构建出具有良好可用性的应用。
 
 <p align="center">
@@ -43,13 +43,12 @@ PyWebIO还可以方便地整合进现有的Web服务，让你不需要编写HTML
 
 功能特性：
 
-- 使用同步而不是基于回调的方式获取输入，无需在各个步骤之间保存状态
+- 使用同步而不是基于回调的方式获取输入，代码编写逻辑更自然
 - 非声明式布局，布局方式简单高效
-- 代码侵入性小，对于旧脚本代码仅需修改输入输出逻辑
-- 支持多用户与并发请求
-- 支持结合第三方库实现数据可视化
+- 代码侵入性小，旧脚本代码仅需修改输入输出逻辑便可改造为Web服务
 - 支持整合到现有的Web服务，目前支持与Flask、Django、Tornado、aiohttp框架集成
 - 同时支持基于线程的执行模型和基于协程的执行模型
+- 支持结合第三方库实现数据可视化
 
 ## Install
 
@@ -118,7 +117,7 @@ def bmi():
     ...  # bmi() 函数内容不变
 
 if __name__ == '__main__':
-    start_server(bmi)
+    start_server(bmi, port=80)
 ```
 
 **与现有Web框架整合**

demos/chat_room.py

@@ -3,7 +3,7 @@
 ^^^^^^^^^^^
 和当前所有在线的人聊天
 
-:demo_host:`Demo地址 </?pywebio_api=chat_room>`  `源码 <https://github.com/wang0618/PyWebIO/blob/master/dev/chat_room.py>`_
+:demo_host:`Demo地址 </?pywebio_api=chat_room>`  `源码 <https://github.com/wang0618/PyWebIO/blob/dev/demos/chat_room.py>`_
 
 * 使用基于协程的会话
 * 使用 `run_async() <pywebio.session.run_async>` 启动后台协程
@@ -46,7 +46,7 @@ async def main():
     set_env(title="PyWebIO Chat Room")
 
     put_markdown("##PyWebIO聊天室\n欢迎来到聊天室，你可以和当前所有在线的人聊天。"
-    "本应用使用不到80行代码实现，源代码[链接](https://github.com/wang0618/PyWebIO/blob/master/dev/chat_room.py)", lstrip=True)
+    "本应用使用不到80行代码实现，源代码[链接](https://github.com/wang0618/PyWebIO/blob/dev/demos/chat_room.py)", lstrip=True)
 
     msg_box = output()
     with use_scope('msg-container'):

docs/guide.rst

@@ -31,9 +31,9 @@ User's guide
     age = input("How old are you?", type=NUMBER)
     put_text('age = %r' % age)  # ..demo-only
 
-这样一行代码的效果为：浏览器会弹出一个文本输入框来获取输入，在用户输入完成将表单提交后，``input`` 函数返回用户输入的值。
+这样一行代码的效果为：浏览器会弹出一个文本输入框来获取输入，在用户完成输入将表单提交后，函数返回用户输入的值。
 
-一些其他类型的输入
+下面是一些其他类型的输入函数:
 
 .. exportable-codeblock::
     :name: basic-input
@@ -66,7 +66,8 @@ User's guide
 
     # 文件上传
     img = file_upload("Select a image:", accept="image/*")
-    put_text('img = %r' % img)  # ..demo-only
+    if img:    # ..demo-only
+        put_image(img['content'], title=img['filename'])  # ..demo-only
 
 
 输入选项
@@ -177,10 +178,12 @@ PyWebIO支持输入组, 返回结果为一个字典。`pywebio.input.input_group
 
 输出函数都定义在 :doc:`pywebio.output </output>` 模块中，可以使用 ``from pywebio.output import *`` 引入。
 
+调用输出函数后，内容会实时输出到浏览器，在应用的生命周期内，可以在任意时刻调用输出函数。
+
 基本输出
 ^^^^^^^^^^^^^^
 
-PyWebIO提供了一些便捷函数来输出表格、链接等格式:
+PyWebIO提供了一系列函数来输出表格、链接等格式:
 
 .. exportable-codeblock::
     :name: basic-output
@@ -229,7 +232,7 @@ PyWebIO提供的全部输出函数见 :doc:`pywebio.output </output>` 模块。
         ['html', put_html('X<sup>2</sup>')],
         ['text', '<hr/>'],  # 等价于 ['text', put_text('<hr/>')]
         ['buttons', put_buttons(['A', 'B'], onclick=...)],  # ..doc-only
-        ['buttons', put_buttons(['A', 'B'], onclick=put_text)],  # ..dome-only
+        ['buttons', put_buttons(['A', 'B'], onclick=put_text)],  # ..demo-only
         ['markdown', put_markdown('`Awesome PyWebIO!`')],
         ['file', put_file('hello.text', b'hello world')],
         ['table', put_table([['A', 'B'], ['C', 'D']])]
@@ -280,8 +283,9 @@ PyWebIO提供的全部输出函数见 :doc:`pywebio.output </output>` 模块。
 事件回调
 ^^^^^^^^^^^^^^
 
-PyWebIO把程序与用户的交互分成了输入和输出两部分：输入函数为阻塞式调用，会在用户浏览器上显示一个表单，在用户提交表单之前输入函数将不会返回；输出函数将内容实时输出至浏览器。
-这非常符合控制台程序的编写逻辑。但PyWebIO能做的还远远不止这些，PyWebIO还允许你输出一些控件，当控件被点击时执行提供的回调函数，就像编写GUI程序一样。
+从上面可以看出，PyWebIO把交互分成了输入和输出两部分：输入函数为阻塞式调用，会在用户浏览器上显示一个表单，在用户提交表单之前输入函数将不会返回；输出函数将内容实时输出至浏览器。这种交互方式和控制台程序是一致的，因此PyWebIO应用非常适合使用控制台程序的编写逻辑来进行开发。
+
+此外，PyWebIO还支持事件回调：PyWebIO允许你输出一些控件，当控件被点击时执行提供的回调函数。
 
 下面是一个例子:
 
@@ -316,7 +320,7 @@ PyWebIO把程序与用户的交互分成了输入和输出两部分：输入函
     put_buttons(['A', 'B', 'C'], onclick=btn_click)
 
 .. note::
-   在PyWebIO会话(关于会话的概念见下文 :ref:`Server与script模式 <server_and_script_mode>` )结束后，事件回调也将不起作用，你可以在任务函数末尾处使用 :func:`pywebio.session.hold()` 函数来将会话保持，这样在用户关闭浏览器前，事件回调将一直可用。
+   在PyWebIO会话(关于会话的概念见下文 :ref:`Server与script模式 <server_and_script_mode>` )结束后，事件回调也将不起作用，你可以在任务函数末尾处使用 :func:`pywebio.session.hold()` 函数来将会话保持，这样在用户关闭浏览器页面前，事件回调将一直可用。
 
 输出域Scope
 ^^^^^^^^^^^^^^
@@ -392,7 +396,7 @@ PyWebIO使用Scope模型来对内容输出的位置进行灵活地控制，PyWeb
 Scope是可嵌套的，初始条件下，PyWebIO应用只有一个最顶层的 ``ROOT`` Scope。每创建一个新Scope，Scope的嵌套层级便会多加一层，每退出当前Scope，Scope的嵌套层级便会减少一层。
 PyWebIO使用Scope栈来保存运行时的Scope的嵌套层级。
 
-例如，如下代码将会创建3个Scope::
+例如，如下代码将会创建3个Scope:
 
 .. exportable-codeblock::
     :name: use-scope-nested
@@ -493,25 +497,24 @@ PyWebIO使用Scope栈来保存运行时的Scope的嵌套层级。
 页面环境设置
 ^^^^^^^^^^^^^^
 
-**设置页面标题**
+**页面标题**
 
 调用 `set_env(title=...) <pywebio.session.set_env>` 可以设置页面标题。
 
 **自动滚动**
 
 在进行一些持续性的输出时(比如日志输出)，有时希望在有新输出后自动将页面滚动到最下方，这时可以调用 `set_env(auto_scroll_bottom=True) <pywebio.session.set_env>` 来开启自动滚动。
-注意，只有输出到ROOT Scope才可以触发自动滚动。
+注意，开启后，只有输出到ROOT Scope才可以触发自动滚动。
 
 **输出动画**
 
-PyWebIO在输出内容时默认会提供内容的显示动画(淡入效果)，可使用 `set_env(output_animation=False) <pywebio.session.set_env>` 来关闭动画。
+PyWebIO在输出内容时默认会使用淡入的动画效果来显示内容，可使用 `set_env(output_animation=False) <pywebio.session.set_env>` 来关闭动画。
 
-上述页面环境配置的效果可查看 :demo_host:`set_env Demo </?pywebio_api=set_env_demo>`
+有关不同环境配置的效果可查看 :demo_host:`set_env Demo </?pywebio_api=set_env_demo>`
 
 布局
 ^^^^^^^^^^^^^^
-一般情况下，使用上文介绍的各种输出函数足以完成各种内容的展示，但直接调用输出函数产生的输出之间都是竖直排列的，如果想实现更复杂的布局（比如在页
-面左侧显示一个代码块，在右侧显示一个图像），就需要借助布局函数。
+一般情况下，使用上文介绍的各种输出函数足以完成各种内容的展示，但直接调用输出函数产生的输出之间都是竖直排列的，如果想实现更复杂的布局（比如在页面左侧显示一个代码块，在右侧显示一个图像），就需要借助布局函数。
 
 ``pywebio.output`` 模块提供了3个布局函数，通过对他们进行组合可以完成各种复杂的布局:
 
@@ -616,7 +619,7 @@ Server模式与Script模式
 
 Script模式下，在任何位置都可以调用PyWebIO的交互函数。
 
-如果用户在会话结束之前关闭了浏览器，那么之后会话内对于PyWebIO交互函数的调用将会引发一个 `pywebio.SessionException` 异常。
+如果用户在会话结束之前关闭了浏览器，那么之后会话内对于PyWebIO交互函数的调用将会引发一个 `SessionException <pywebio.exceptions.SessionException>` 异常。
 
 .. _thread_in_server_mode:
 
@@ -632,18 +635,41 @@ PyWebIO 支持在多线程环境中使用。
 **Server模式**
 
 Server模式下，如果需要在新创建的线程中使用PyWebIO的交互函数，需要手动调用 `register_thread(thread) <pywebio.session.register_thread>` 对新进程进行注册（这样PyWebIO才能知道新创建的线程属于哪个会话）。
-如果新创建的线程中没有使用到PyWebIO的交互函数，则无需注册。在没有使用 `register_thread(thread) <pywebio.session.register_thread>` 注册的线程不受会话管理，其调用PyWebIO的交互函数将会产生 `SessionNotFoundException <pywebio.exceptions.SessionNotFoundException>` 异常。
+如果新创建的线程中没有使用到PyWebIO的交互函数，则无需注册。没有使用 `register_thread(thread) <pywebio.session.register_thread>` 注册的线程不受会话管理，其调用PyWebIO的交互函数将会产生 `SessionNotFoundException <pywebio.exceptions.SessionNotFoundException>` 异常。
 当会话的任务函数和会话内通过 `register_thread(thread) <pywebio.session.register_thread>` 注册的线程都结束运行时，会话关闭。
 
+Server模式下多线程的使用示例::
+
+   def show_time():
+       while True:
+           with use_scope(name='time', clear=True):
+               put_text(datetime.datetime.now())
+               time.sleep(1)
+
+   def app():
+       t = threading.Thread(target=show_time)
+       register_thread(t)
+       put_markdown('## Clock')
+       t.start()  # 在后台运行show_time()
+
+       # ❌ 没有使用register_thread注册的线程调用PyWebIO交互函数会产生异常
+       threading.Thread(target=show_time).start()
+
+       put_text('Background task started.')
+
+
+   start_server(app, port=8080, debug=True)
+
+
 .. _session_close:
 
 会话的结束
 ^^^^^^^^^^^^^^
 
-会话还会因为用户的关闭浏览器而结束，这时当前会话内还未返回的PyWebIO输入函数调用将抛出 `SessionClosedException <pywebio.exceptions.SessionClosedException>` 异常，之后对于PyWebIO交互函数的调用将会产生 `SessionNotFoundException <pywebio.exceptions.SessionNotFoundException>` / `SessionClosedException <pywebio.exceptions.SessionClosedException>` 异常。
+会话还会因为用户的关闭浏览器而结束，这时当前会话内还未返回的PyWebIO输入函数调用将抛出 `SessionClosedException <pywebio.exceptions.SessionClosedException>` 异常，之后对于PyWebIO交互函数的调用将会产生 `SessionNotFoundException <pywebio.exceptions.SessionNotFoundException>` 或 `SessionClosedException <pywebio.exceptions.SessionClosedException>` 异常。
 
-可以使用 `defer_call(func) <pywebio.session.defer_call>` 来设置会话结束时需要调用的函数。无论是用户主动关闭会话还是任务结束会话关闭，设置的函数都会被执行。
-可以用于资源清理等工作。在会话中可以多次调用 `defer_call() <pywebio.session.defer_call>` ,会话结束后将会顺序执行设置的函数。
+可以使用 `defer_call(func) <pywebio.session.defer_call>` 来设置会话结束时需要调用的函数。无论是因为用户主动关闭页面还是任务结束使得会话关闭，设置的函数都会被执行。
+`defer_call(func) <pywebio.session.defer_call>` 可以用于资源清理等工作。在会话中可以多次调用 `defer_call() <pywebio.session.defer_call>` ,会话结束后将会顺序执行设置的函数。
 
 
 与Web框架集成
@@ -653,7 +679,7 @@ Server模式下，如果需要在新创建的线程中使用PyWebIO的交互函
 
 可以将PyWebIO应用集成到现有的Python Web项目中，PyWebIO应用与Web项目共用一个Web框架。目前支持与Flask、Tornado、Django和aiohttp Web框架的集成。
 
-与Web框架集成需要完成两件工作：托管PyWebIO静态文件；暴露PyWebIO后端接口。这其中需要注意前端页面和后端接口的路径约定，
+与Web框架集成需要完成两部分配置：托管PyWebIO前端静态文件；暴露PyWebIO后端接口。这其中需要注意前端页面和后端接口的路径约定，
 以及前端静态文件与后端接口分开部署时因为跨域而需要的特别设置。
 
 集成方法
@@ -813,7 +839,7 @@ PyWebIO默认通过当前页面的同级的 ``./io`` API与后端进行通讯。
 PyWebIO的会话实现默认是基于线程的，用户每打开一个和服务端的会话连接，PyWebIO会启动一个线程来运行任务函数。
 除了基于线程的会话，PyWebIO还提供了基于协程的会话。基于协程的会话接受协程函数作为任务函数。
 
-基于线程的会话为单线程模型，所有会话都运行在一个线程内。对于IO密集型的任务，协程比线程有更少的资源占用同时又拥有媲美于线程的性能。
+基于协程的会话为单线程模型，所有会话都运行在一个线程内。对于IO密集型的任务，协程比线程占用更少的资源同时又拥有媲美于线程的性能。
 
 使用协程会话
 ^^^^^^^^^^^^^^^^
@@ -876,7 +902,7 @@ PyWebIO的会话实现默认是基于线程的，用户每打开一个和服务
 协程会话的并发
 ^^^^^^^^^^^^^^^^
 
-在基于协程的会话中，你可以启动线程，但是无法像基于线程的会话那样使用 `register_thread() <pywebio.session.register_thread>` 函数来使得在新线程内使用PyWebIO交互函数。
+在基于协程的会话中，你可以启动线程，但是无法在其中调用PyWebIO交互函数（ `register_thread() <pywebio.session.register_thread>` 在协程会话中不可用）。
 但你可以使用 `run_async(coro) <pywebio.session.run_async>` 来异步执行一个协程对象，新协程内可以使用PyWebIO交互函数::
 
     from pywebio import start_server
@@ -889,18 +915,21 @@ PyWebIO的会话实现默认是基于线程的，用户每打开一个和服务
 
     async def main():
         run_async(counter(10))
-        put_text('Bye, bye')
+        put_text('Main coroutine function exited.')
 
 
     start_server(main, auto_open_webbrowser=True)
 
-`run_async(coro) <pywebio.session.run_async>` 返回一个 `TaskHandle <pywebio.session.coroutinebased.TaskHandle>` ，通过 `TaskHandle <pywebio.session.coroutinebased.TaskHandle>` 你可以查询协程运行状态和关闭协程。
+`run_async(coro) <pywebio.session.run_async>` 返回一个 `TaskHandle <pywebio.session.coroutinebased.TaskHandle>` ，通过 `TaskHandle <pywebio.session.coroutinebased.TaskHandle>` 可以查询协程运行状态和关闭协程。
 
 协程会话的关闭
 ^^^^^^^^^^^^^^^^
 与基于线程的会话类似，在基于协程的会话中，当任务函数和在会话内通过 `run_async() <pywebio.session.run_async>` 运行的协程全部结束后，会话关闭。
 
-对于因为用户的关闭浏览器而造成的会话结束，处理逻辑和 :ref:`基于线程的会话 <session_close>` 一致。协程会话也同样支持使用 `defer_call(func) <pywebio.session.defer_call>` 来设置会话结束时需要调用的函数。
+对于因为用户的关闭浏览器而造成的会话结束，处理逻辑和 :ref:`基于线程的会话 <session_close>` 一致:
+此时当前会话内还未返回的PyWebIO输入函数调用将抛出 `SessionClosedException <pywebio.exceptions.SessionClosedException>` 异常，之后对于PyWebIO交互函数的调用将会产生 `SessionNotFoundException <pywebio.exceptions.SessionNotFoundException>` 或 `SessionClosedException <pywebio.exceptions.SessionClosedException>` 异常。
+
+协程会话也同样支持使用 `defer_call(func) <pywebio.session.defer_call>` 来设置会话结束时需要调用的函数。
 
 协程会话与Web框架集成
 ^^^^^^^^^^^^^^^^^^^^^^^^^

docs/index.rst

@@ -1,20 +1,20 @@
 PyWebIO
 ==========
 
-PyWebIO提供了一系列命令式的交互函数来在浏览器上获取用户输入和进行输出，可以用于构建简单的Web应用或基于浏览器的GUI应用。
-使用PyWebIO，开发者能像编写终端脚本一样(基于input和print进行交互)来编写应用，无需具备HTML和JS的相关知识。
-PyWebIO还可以方便地整合进现有的Web框架，非常适合在短时间内快速构建对UI要求不高的应用。
+PyWebIO提供了一系列命令式的交互函数来在浏览器上获取用户输入和进行输出，将浏览器变成了一个“富文本终端”，可以用于构建简单的Web应用或基于浏览器的GUI应用。
+使用PyWebIO，开发者能像编写终端脚本一样(基于input和print进行交互)来编写应用，无需具备HTML和JS的相关知识；
+PyWebIO还可以方便地整合进现有的Web框架。非常适合在短时间内快速构建对UI要求不高的应用。
 
 
 特性
 ------------
 
-- 使用同步而不是基于回调的方式获取输入，无需在各个步骤之间保存状态，使用更方便
-- 代码侵入性小，对于旧脚本代码仅需修改输入输出逻辑
-- 支持多用户与并发请求
+- 使用同步而不是基于回调的方式获取输入，代码编写逻辑更自然
+- 非声明式布局，布局方式简单高效
+- 代码侵入性小，旧脚本代码仅需修改输入输出逻辑便可改造为Web服务
 - 支持整合到现有的Web服务，目前支持与Flask、Django、Tornado、aiohttp框架集成
 - 同时支持基于线程的执行模型和基于协程的执行模型
-
+- 支持结合第三方库实现数据可视化
 
 Install
 ------------

docs/libraries_support.rst

@@ -21,7 +21,7 @@ Bokeh
     ...
     show(fig)
 
-相应demo见 :charts_demo_host:`bokeh demo </?pywebio_api=bokeh>`
+相应demo见 :charts_demo_host:`bokeh demo </?app=bokeh>`
 
 除了创建普通图表，Bokeh还可以通过启动Bokeh server来显示Bokeh app，Bokeh app支持向图表的添加按钮、输入框等交互组件，并向组件注册Python回调，从而创建可以与Python代码交互的图表。
 
@@ -38,7 +38,7 @@ pyecharts
     # chart 为 pyecharts 的图表实例
     pywebio.output.put_html(chart.render_notebook())
 
-相应demo见 :charts_demo_host:`pyecharts demo </?pywebio_api=pyecharts>`
+相应demo见 :charts_demo_host:`pyecharts demo </?app=pyecharts>`
 
 .. only:: not latex
 
@@ -54,7 +54,7 @@ PyWebIO 支持输出使用 plotly 库创建的图表。使用方式为在PyWebIO
     html = fig.to_html(include_plotlyjs="require", full_html=False)
     pywebio.output.put_html(html)
 
-相应demo见 :charts_demo_host:`plotly demo </?pywebio_api=plotly>`
+相应demo见 :charts_demo_host:`plotly demo </?app=plotly>`
 
 .. image:: https://cdn.jsdelivr.net/gh/wang0618/pywebio-chart-gallery@master/assets/plotly.png
 
@@ -69,6 +69,6 @@ cutecharts.py
     # chart 为 cutecharts 的图表实例
     pywebio.output.put_html(chart.render_notebook())
 
-相应demo见 :charts_demo_host:`cutecharts demo </?pywebio_api=cutecharts>`
+相应demo见 :charts_demo_host:`cutecharts demo </?app=cutecharts>`
 
 .. image:: https://cdn.jsdelivr.net/gh/wang0618/pywebio-chart-gallery@master/assets/cutecharts.png

docs/static/pywebio.css

@@ -32,4 +32,16 @@ td .line-block {
     box-shadow: none;
     -moz-box-shadow: none;
     -webkit-box-shadow: none;
+}
+
+.demo-cb .highlight{
+    position: relative;
+}
+
+.demo-cb .viewcode-back{
+    position: absolute;
+    right: 10px;
+    top: 4px;
+    padding-left: 0px;
+    background-color: #f8f8f8;
 }

docs/static/pywebio.js

@@ -24,7 +24,7 @@ ready(function () {
     let codes = document.querySelectorAll('.demo-cb');
     for (let c of codes) {
         let id = c.getAttribute('id');
-        let ele = c.querySelector('.highlight > pre');
+        let ele = c.querySelector('.highlight');
         demo_url.searchParams.set("app", id);
         let node = parseHTML(`<a class="viewcode-back" href="${demo_url.href}" target="_blank">[Demo]</a>`)[0];
         ele.insertBefore(node, ele.firstChild);

pywebio/input.py

@@ -578,7 +578,15 @@ def file_upload(label='', accept=None, name=None, placeholder='Choose file', mul
     :param int/str max_total_size: 所有文件的最大大小，超过限制将会禁止上传。仅在 ``multiple=True`` 时可用，默认不限制上传文件的大小。 格式同 ``max_size`` 参数
     :param bool required: 是否必须要上传文件。默认为 `False`
     :param - label, name, help_text, other_html_attrs: 与 `input` 输入函数的同名参数含义一致
-    :return: ``multiple=False`` 时(默认)，返回dict: ``{'filename': 文件名， 'content'：文件二进制数据(bytes object), mime_type: 文件的MIME类型, last_modified: 文件上次修改时间(时间戳) }`` ；
+    :return: ``multiple=False`` 时(默认)，返回dict::
+
+        {
+            'filename': 文件名， 
+            'content'：文件二进制数据(bytes object), 
+            'mime_type': 文件的MIME类型, 
+            'last_modified': 文件上次修改时间(时间戳) 
+        }
+       
        若用户没有上传文件，返回 ``None`` 。
 
        ``multiple=True`` 时，返回列表，列表项格式同上文 ``multiple=False`` 时的返回值；若用户没有上传文件，返回空列表。

pywebio/platform/__init__.py

@@ -5,7 +5,7 @@ r"""
 
 Tornado相关
 --------------
-.. autofunction:: start_server
+.. autofunction:: pywebio.platform.tornado.start_server
 .. autofunction:: pywebio.platform.tornado.webio_handler
 
 Flask相关

pywebio/platform/aiohttp.py

@@ -105,19 +105,13 @@ def webio_handler(applications, allowed_origins=None, check_origin=None, websock
     """获取在aiohttp中运行PyWebIO任务函数的 `Request Handle <https://docs.aiohttp.org/en/stable/web_quickstart.html#aiohttp-web-handler>`_ 协程。
     Request Handle基于WebSocket协议与浏览器进行通讯。
 
-    :param list/dict/callable applications: PyWebIO应用. 格式同 :func:`pywebio.platform.start_server` 的 ``applications`` 参数
+    :param list/dict/callable applications: PyWebIO应用。
     :param list allowed_origins: 除当前域名外，服务器还允许的请求的来源列表。
-        来源包含协议和域名和端口部分，允许使用 Unix shell 风格的匹配模式:
+    :param callable check_origin: 请求来源检查函数。
+    :param dict websocket_settings: 创建 aiohttp WebSocketResponse 时使用的参数。见 https://docs.aiohttp.org/en/stable/web_reference.html#websocketresponse
 
-        - ``*`` 为通配符
-        - ``?`` 匹配单个字符
-        - ``[seq]`` 匹配seq内的字符
-        - ``[!seq]`` 匹配不在seq内的字符
+    关于 ``applications`` 、 ``allowed_origins`` 、 ``check_origin`` 参数的详细说明见 :func:`pywebio.platform.aiohttp.start_server` 的同名参数。
 
-        比如 ``https://*.example.com`` 、 ``*://*.example.com`` 、
-    :param callable check_origin: 请求来源检查函数。接收请求来源(包含协议和域名和端口部分)字符串，
-        返回 ``True/False`` 。若设置了 ``check_origin`` ， ``allowed_origins`` 参数将被忽略
-    :param dict websocket_settings: 创建 aiohttp WebSocketResponse 时使用的参数。见 https://docs.aiohttp.org/en/stable/web_reference.html#websocketresponse
     :return: aiohttp Request Handler
     """
     applications = make_applications(applications)
@@ -160,23 +154,23 @@ def start_server(applications, port=0, host='', debug=False,
                  **aiohttp_settings):
     """启动一个 aiohttp server 将PyWebIO应用作为Web服务提供。
 
-    :param list/dict/callable applications: PyWebIO应用. 格式同 :func:`pywebio.platform.start_server` 的 ``applications`` 参数
+    :param list/dict/callable applications: PyWebIO应用. 格式同 :func:`pywebio.platform.tornado.start_server` 的 ``applications`` 参数
     :param int port: 服务监听的端口。设置为 ``0`` 时，表示自动选择可用端口。
     :param str host: 服务绑定的地址。 ``host`` 可以是IP地址或者为hostname。如果为hostname，服务会监听所有与该hostname关联的IP地址。
         通过设置 ``host`` 为空字符串或 ``None`` 来将服务绑定到所有可用的地址上。
     :param bool debug: 是否开启asyncio的Debug模式
     :param list allowed_origins: 除当前域名外，服务器还允许的请求的来源列表。
-        来源包含协议和域名和端口部分，允许使用 Unix shell 风格的匹配模式:
+        来源包含协议、域名和端口部分，允许使用 Unix shell 风格的匹配模式(全部规则参见 `Python文档 <https://docs.python.org/zh-tw/3/library/fnmatch.html>`_ ):
 
         - ``*`` 为通配符
         - ``?`` 匹配单个字符
-        - ``[seq]`` 匹配seq内的字符
-        - ``[!seq]`` 匹配不在seq内的字符
+        - ``[seq]`` 匹配seq中的字符
+        - ``[!seq]`` 匹配不在seq中的字符
 
         比如 ``https://*.example.com`` 、 ``*://*.example.com``
-    :param callable check_origin: 请求来源检查函数。接收请求来源(包含协议和域名和端口部分)字符串，
+    :param callable check_origin: 请求来源检查函数。接收请求来源(包含协议、域名和端口部分)字符串，
         返回 ``True/False`` 。若设置了 ``check_origin`` ， ``allowed_origins`` 参数将被忽略
-    :param bool auto_open_webbrowser: Whether or not auto open web browser when server is started (if the operating system allows it) .
+    :param bool auto_open_webbrowser: 当服务启动后，是否自动打开浏览器来访问服务。（该操作需要操作系统支持）
     :param dict websocket_settings: 创建 aiohttp WebSocketResponse 时使用的参数。见 https://docs.aiohttp.org/en/stable/web_reference.html#websocketresponse
     :param aiohttp_settings: 需要传给 aiohttp Application 的参数。可用参数见 https://docs.aiohttp.org/en/stable/web_reference.html#application
     """

pywebio/platform/django.py

@@ -78,20 +78,14 @@ def webio_view(applications,
     """获取在django中运行PyWebIO任务的视图函数。
     基于http请求与前端进行通讯
 
-    :param list/dict/callable applications: PyWebIO应用. 格式同 :func:`pywebio.platform.start_server` 的 ``applications`` 参数
+    :param list/dict/callable applications: PyWebIO应用。
     :param int session_expire_seconds: 会话不活跃过期时间。
     :param int session_cleanup_interval: 会话清理间隔。
     :param list allowed_origins: 除当前域名外，服务器还允许的请求的来源列表。
-        来源包含协议和域名和端口部分，允许使用 Unix shell 风格的匹配模式:
+    :param callable check_origin: 请求来源检查函数。
 
-        - ``*`` 为通配符
-        - ``?`` 匹配单个字符
-        - ``[seq]`` 匹配seq内的字符
-        - ``[!seq]`` 匹配不在seq内的字符
+    关于各参数的详细说明见 :func:`pywebio.platform.django.start_server` 的同名参数。
 
-        比如 ``https://*.example.com`` 、 ``*://*.example.com``
-    :param callable check_origin: 请求来源检查函数。接收请求来源(包含协议和域名和端口部分)字符串，
-        返回 ``True/False`` 。若设置了 ``check_origin`` ， ``allowed_origins`` 参数将被忽略
     :return: Django视图函数
     """
     handler = HttpHandler(applications=applications,
@@ -120,20 +114,20 @@ def start_server(applications, port=8080, host='localhost',
                  debug=False, **django_options):
     """启动一个 Django server 将PyWebIO应用作为Web服务提供。
 
-    :param list/dict/callable applications: PyWebIO应用. 格式同 :func:`pywebio.platform.start_server` 的 ``applications`` 参数
+    :param list/dict/callable applications: PyWebIO应用. 格式同 :func:`pywebio.platform.tornado.start_server` 的 ``applications`` 参数
     :param int port: 服务监听的端口。设置为 ``0`` 时，表示自动选择可用端口。
     :param str host: 服务绑定的地址。 ``host`` 可以是IP地址或者为hostname。如果为hostname，服务会监听所有与该hostname关联的IP地址。
         通过设置 ``host`` 为空字符串或 ``None`` 来将服务绑定到所有可用的地址上。
     :param list allowed_origins: 除当前域名外，服务器还允许的请求的来源列表。
-        来源包含协议和域名和端口部分，允许使用 Unix shell 风格的匹配模式:
+        来源包含协议、域名和端口部分，允许使用 Unix shell 风格的匹配模式(全部规则参见 `Python文档 <https://docs.python.org/zh-tw/3/library/fnmatch.html>`_ ):
 
         - ``*`` 为通配符
         - ``?`` 匹配单个字符
-        - ``[seq]`` 匹配seq内的字符
-        - ``[!seq]`` 匹配不在seq内的字符
+        - ``[seq]`` 匹配seq中的字符
+        - ``[!seq]`` 匹配不在seq中的字符
 
         比如 ``https://*.example.com`` 、 ``*://*.example.com``
-    :param callable check_origin: 请求来源检查函数。接收请求来源(包含协议和域名和端口部分)字符串，
+    :param callable check_origin: 请求来源检查函数。接收请求来源(包含协议、域名和端口部分)字符串，
         返回 ``True/False`` 。若设置了 ``check_origin`` ， ``allowed_origins`` 参数将被忽略
     :param bool disable_asyncio: 禁用 asyncio 函数。仅在任务函数为协程函数时有效。
 

pywebio/platform/flask.py

@@ -81,22 +81,16 @@ def webio_view(applications,
                session_expire_seconds=None,
                session_cleanup_interval=None,
                allowed_origins=None, check_origin=None):
-    """获取在Flask中运行PyWebIO任务的视图函数。基于http请求与前端进行通讯
+    """获取在Flask中运行PyWebIO任务的视图函数。基于http请求与前端页面进行通讯
 
-    :param list/dict/callable applications: PyWebIO应用. 格式同 :func:`pywebio.platform.start_server` 的 ``applications`` 参数
+    :param list/dict/callable applications: PyWebIO应用。
     :param int session_expire_seconds: 会话不活跃过期时间。
     :param int session_cleanup_interval: 会话清理间隔。
     :param list allowed_origins: 除当前域名外，服务器还允许的请求的来源列表。
-        来源包含协议和域名和端口部分，允许使用 Unix shell 风格的匹配模式:
+    :param callable check_origin: 请求来源检查函数。
 
-        - ``*`` 为通配符
-        - ``?`` 匹配单个字符
-        - ``[seq]`` 匹配seq内的字符
-        - ``[!seq]`` 匹配不在seq内的字符
+    关于各参数的详细说明见 :func:`pywebio.platform.flask.start_server` 的同名参数。
 
-        比如 ``https://*.example.com`` 、 ``*://*.example.com``
-    :param callable check_origin: 请求来源检查函数。接收请求来源(包含协议和域名和端口部分)字符串，
-        返回 ``True/False`` 。若设置了 ``check_origin`` ， ``allowed_origins`` 参数将被忽略
     :return: Flask视图函数
     """
 
@@ -121,20 +115,20 @@ def start_server(applications, port=8080, host='localhost',
                  debug=False, **flask_options):
     """启动一个 Flask server 将PyWebIO应用作为Web服务提供。
 
-    :param list/dict/callable applications: PyWebIO应用. 格式同 :func:`pywebio.platform.start_server` 的 ``applications`` 参数
+    :param list/dict/callable applications: PyWebIO应用. 格式同 :func:`pywebio.platform.tornado.start_server` 的 ``applications`` 参数
     :param int port: 服务监听的端口。设置为 ``0`` 时，表示自动选择可用端口。
     :param str host: 服务绑定的地址。 ``host`` 可以是IP地址或者为hostname。如果为hostname，服务会监听所有与该hostname关联的IP地址。
         通过设置 ``host`` 为空字符串或 ``None`` 来将服务绑定到所有可用的地址上。
     :param list allowed_origins: 除当前域名外，服务器还允许的请求的来源列表。
-        来源包含协议和域名和端口部分，允许使用 Unix shell 风格的匹配模式:
+        来源包含协议、域名和端口部分，允许使用 Unix shell 风格的匹配模式(全部规则参见 `Python文档 <https://docs.python.org/zh-tw/3/library/fnmatch.html>`_ ):
 
         - ``*`` 为通配符
         - ``?`` 匹配单个字符
-        - ``[seq]`` 匹配seq内的字符
-        - ``[!seq]`` 匹配不在seq内的字符
+        - ``[seq]`` 匹配seq中的字符
+        - ``[!seq]`` 匹配不在seq中的字符
 
         比如 ``https://*.example.com`` 、 ``*://*.example.com``
-    :param callable check_origin: 请求来源检查函数。接收请求来源(包含协议和域名和端口部分)字符串，
+    :param callable check_origin: 请求来源检查函数。接收请求来源(包含协议、域名和端口部分)字符串，
         返回 ``True/False`` 。若设置了 ``check_origin`` ， ``allowed_origins`` 参数将被忽略
     :param bool disable_asyncio: 禁用 asyncio 函数。仅在任务函数为协程函数时有效。
 

pywebio/platform/tornado.py

@@ -114,20 +114,14 @@ def _webio_handler(applications, check_origin_func=_is_same_site):
 
 
 def webio_handler(applications, allowed_origins=None, check_origin=None):
-    """获取在Tornado中运行PyWebIO任务的RequestHandle类。RequestHandle类基于WebSocket协议与浏览器进行通讯。
+    """获取在Tornado中运行PyWebIO应用的RequestHandle类。RequestHandle类基于WebSocket协议与浏览器进行通讯。
 
-    :param callable/list/dict applications: PyWebIO应用. 格式同 :func:`pywebio.platform.start_server` 的 ``applications`` 参数
+    :param callable/list/dict applications: PyWebIO应用。
     :param list allowed_origins: 除当前域名外，服务器还允许的请求的来源列表。
-        来源包含协议和域名和端口部分，允许使用 Unix shell 风格的匹配模式:
+    :param callable check_origin: 请求来源检查函数。
 
-        - ``*`` 为通配符
-        - ``?`` 匹配单个字符
-        - ``[seq]`` 匹配seq内的字符
-        - ``[!seq]`` 匹配不在seq内的字符
+    关于各参数的详细说明见 :func:`pywebio.platform.tornado.start_server` 的同名参数。
 
-        比如 ``https://*.example.com`` 、 ``*://*.example.com`` 、
-    :param callable check_origin: 请求来源检查函数。接收请求来源(包含协议和域名和端口部分)字符串，
-        返回 ``True/False`` 。若设置了 ``check_origin`` ， ``allowed_origins`` 参数将被忽略
     :return: Tornado RequestHandle类
     """
     applications = make_applications(applications)
@@ -173,6 +167,8 @@ def start_server(applications, port=0, host='', debug=False,
                  **tornado_app_settings):
     """启动一个 Tornado server 将PyWebIO应用作为Web服务提供。
 
+    Tornado为PyWebIO应用的默认后端Server，可以直接使用 ``from pywebio import start_server`` 导入。
+
     :param list/dict/callable applications: PyWebIO应用. 可以是任务函数或者任务函数的字典或列表。
 
        类型为字典时，字典键为任务名，类型为列表时，函数名为任务名。
@@ -186,23 +182,23 @@ def start_server(applications, port=0, host='', debug=False,
        通过设置 ``host`` 为空字符串或 ``None`` 来将服务绑定到所有可用的地址上。
     :param bool debug: Tornado Server是否开启debug模式
     :param list allowed_origins: 除当前域名外，服务器还允许的请求的来源列表。
-        来源包含协议和域名和端口部分，允许使用 Unix shell 风格的匹配模式:
+        来源包含协议、域名和端口部分，允许使用 Unix shell 风格的匹配模式(全部规则参见 `Python文档 <https://docs.python.org/zh-tw/3/library/fnmatch.html>`_ ):
 
         - ``*`` 为通配符
         - ``?`` 匹配单个字符
-        - ``[seq]`` 匹配seq内的字符
-        - ``[!seq]`` 匹配不在seq内的字符
+        - ``[seq]`` 匹配seq中的任何字符
+        - ``[!seq]`` 匹配任何不在seq中的字符
 
         比如 ``https://*.example.com`` 、 ``*://*.example.com``
-    :param callable check_origin: 请求来源检查函数。接收请求来源(包含协议和域名和端口部分)字符串，
+    :param callable check_origin: 请求来源检查函数。接收请求来源(包含协议、域名和端口部分)字符串，
         返回 ``True/False`` 。若设置了 ``check_origin`` ， ``allowed_origins`` 参数将被忽略
     :param bool auto_open_webbrowser: 当服务启动后，是否自动打开浏览器来访问服务。（该操作需要操作系统支持）
     :param int websocket_max_message_size: Tornado Server最大可接受的WebSockets消息大小。单位为字节，默认为10MiB。
     :param int websocket_ping_interval: 当被设置后，服务器会以 ``websocket_ping_interval`` 秒周期性地向每个WebSockets连接发送‘ping‘消息。
-        如果服务器是在周期性关闭空闲连接的代理服务器后，设置 ``websocket_ping_interval`` 可以避免WebSockets连接被代理服务器当作空闲连接而关闭。
-        同时，若WebSockets连接在某些情况下被异常关闭，也可以及时感知。
-    :param int websocket_ping_timeout: 如果设置了 ``websocket_ping_interval`` ，而服务器没有在发送‘ping‘消息后的 ``websocket_ping_timeout`` 秒
-        内收到‘pong’消息，服务器会将连接关闭。默认的超时时间为 ``websocket_ping_interval`` 的三倍。
+        如果应用处在某些反向代理服务器之后，设置 ``websocket_ping_interval`` 可以避免WebSockets连接被代理服务器当作空闲连接而关闭。
+        同时，若WebSockets连接在某些情况下被异常关闭，应用也可以及时感知。
+    :param int websocket_ping_timeout: 如果设置了 ``websocket_ping_interval`` ，而服务没有在发送‘ping‘消息后的 ``websocket_ping_timeout`` 秒
+        内收到‘pong’消息，应用会将连接关闭。默认的超时时间为 ``websocket_ping_interval`` 的三倍。
     :param tornado_app_settings: 传递给 ``tornado.web.Application`` 构造函数的额外的关键字参数
         可设置项参考: https://www.tornadoweb.org/en/stable/web.html#tornado.web.Application.settings
     """

pywebio/session/__init__.py

@@ -132,8 +132,7 @@ def next_client_event():
 
 @chose_impl
 def hold():
-    """保持会话，直到用户关闭浏览器，
-    此时函数抛出 `SessionClosedException <pywebio.exceptions.SessionClosedException>` 异常。
+    """保持会话，直到用户关闭浏览器
 
     注意⚠️：在 :ref:`基于协程 <coroutine_based_session>` 的会话上下文中，需要使用 ``await hold()`` 语法来进行调用。
     """
@@ -216,7 +215,7 @@ def run_async(coro_obj):
     """异步运行协程对象。协程中依然可以调用 PyWebIO 交互函数。 仅能在 :ref:`基于协程 <coroutine_based_session>` 的会话上下文中调用
 
     :param coro_obj: 协程对象
-    :return: An instance of  `TaskHandle <pywebio.session.coroutinebased.TaskHandle>` is returned, which can be used later to close the task.
+    :return: `TaskHandle <pywebio.session.coroutinebased.TaskHandle>` 实例。 通过 TaskHandle 可以查询协程运行状态和关闭协程。
     """
     return get_current_session().run_async(coro_obj)
 
@@ -287,7 +286,7 @@ def set_env(**env_info):
     * ``title`` (str): 当前页面的标题
     * ``output_animation`` (bool): 是否启用输出动画（在输出内容时，使用过渡动画），默认启用
     * ``auto_scroll_bottom`` (bool): 是否在内容输出时将页面自动滚动到底部，默认关闭。注意，开启后，只有输出到ROOT Scope才可以触发自动滚动。
-    * ``http_pull_interval`` (int): HTTP轮训后端消息的周期（单位为毫秒，默认1000ms），仅在使用HTTP的连接中可用
+    * ``http_pull_interval`` (int): HTTP轮询后端消息的周期（单位为毫秒，默认1000ms），仅在基于HTTP连接的会话中可用（）
 
     调用示例::
 
@@ -346,6 +345,6 @@ def get_info():
             * 使用Django后端时, ``request`` 为 `django.http.HttpRequest <https://docs.djangoproject.com/en/3.0/ref/request-response/#django.http.HttpRequest>`_ 实例
             * 使用aiohttp后端时, ``request`` 为 `aiohttp.web.BaseRequest <https://docs.aiohttp.org/en/stable/web_reference.html#aiohttp.web.BaseRequest>`_ 实例
 
-    返回值的 ``user_agent`` 属性是通过 user-agents 库进行解析生成的。参见 https://github.com/selwin/python-user-agents#usage
+    会话信息对象的 ``user_agent`` 属性是通过 user-agents 库进行解析生成的。参见 https://github.com/selwin/python-user-agents#usage
     """
     return get_current_session().info