doc: update doc

pywebio/input.py

@@ -503,6 +503,12 @@ def file_upload(label='', accept=None, name=None, placeholder='Choose file', mul
        若用户没有上传文件，返回 ``None`` 。
 
        ``multiple=True`` 时，返回列表，列表项格式同上文 ``multiple=False`` 时的返回值；若用户没有上传文件，返回空列表。
+
+    .. note::
+    
+        若上传大文件请留意Web框架的文件上传大小限制设置。在使用 :func:`start_server <pywebio.platform.start_server>` 启动PyWebIO应用时，
+        可通过 `websocket_max_message_size` 参数设置允许上传的最大文件大小
+
     """
     item_spec, valid_func = _parse_args(locals())
     item_spec['type'] = 'file'

pywebio/output.py

@@ -236,7 +236,7 @@ def put_text(*texts, sep=' ', inline=False, scope=Scope.Current, position=Output
     """
     输出文本内容
 
-    :param texts: 要输出的内容，类型可以为任意对象。会对非字符串对象使用 `str()` 函数转化为输出值。
+    :param texts: 要输出的内容。类型可以为任意对象，对非字符串对象会应用 `str()` 函数作为输出值。
     :param str sep: 输出分隔符
     :param bool inline: 文本行末不换行。默认换行
     :param int/str scope: 内容输出的目标scope，若scope不存在，则不进行任何输出操作。
@@ -1191,7 +1191,7 @@ clear_scope = clear
 def use_scope(name=None, clear=False, create_scope=True, **scope_params):
     """scope的上下文管理器和装饰器
 
-    :param name: scope名. 若为None则生成一个全局唯一的scope名
+    :param name: scope名. 若为None则生成一个全局唯一的scope名.（以上下文管理器形式的调用时，上下文管理器会返回scope名）
     :param bool clear: 是否要清除scope内容
     :param bool create_scope: scope不存在时是否创建scope
     :param scope_params: 创建scope时传入set_scope()的参数. 仅在 `create_scope=True` 时有效.
@@ -1200,7 +1200,7 @@ def use_scope(name=None, clear=False, create_scope=True, **scope_params):
 
     ::
 
-        with use_scope(...):
+        with use_scope(...) as scope_name:
             put_xxx()
 
         @use_scope(...)

pywebio/platform/aiohttp.py

@@ -161,12 +161,10 @@ def start_server(applications, port=0, host='', debug=False,
     """启动一个 aiohttp server 将PyWebIO应用作为Web服务提供。
 
     :param list/dict/callable applications: PyWebIO应用. 格式同 :func:`pywebio.platform.start_server` 的 ``applications`` 参数
-    :param list allowed_origins: 除当前域名外，服务器还允许的请求的来源列表。
-    :param int port: server bind port. set ``0`` to find a free port number to use
-    :param str host: server bind host. ``host`` may be either an IP address or hostname.  If it's a hostname,
-        the server will listen on all IP addresses associated with the name.
-        set empty string or to listen on all available interfaces.
-    :param bool debug: asyncio Debug Mode
+    :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 风格的匹配模式:
 

pywebio/platform/django.py

@@ -121,9 +121,9 @@ def start_server(applications, port=8080, host='localhost',
     """启动一个 Django server 将PyWebIO应用作为Web服务提供。
 
     :param list/dict/callable applications: PyWebIO应用. 格式同 :func:`pywebio.platform.start_server` 的 ``applications`` 参数
-    :param int port: server bind port. set ``0`` to find a free port number to use
-    :param str host: server bind host. ``host`` may be either an IP address or hostname.
-       set empty string or `None` to listen on all available interfaces.
+    :param int port: 服务监听的端口。设置为 ``0`` 时，表示自动选择可用端口。
+    :param str host: 服务绑定的地址。 ``host`` 可以是IP地址或者为hostname。如果为hostname，服务会监听所有与该hostname关联的IP地址。
+        通过设置 ``host`` 为空字符串或 ``None`` 来将服务绑定到所有可用的地址上。
     :param list allowed_origins: 除当前域名外，服务器还允许的请求的来源列表。
         来源包含协议和域名和端口部分，允许使用 Unix shell 风格的匹配模式:
 
@@ -145,7 +145,7 @@ def start_server(applications, port=8080, host='localhost',
     :param int session_cleanup_interval: 会话清理间隔。
     :param bool debug: 开启 Django debug mode 和一般访问日志的记录
     :param django_options: django应用的其他设置，见 https://docs.djangoproject.com/en/3.0/ref/settings/ .
-        其中 ``DEBUG`` 、 ``ALLOWED_HOSTS`` 、 ``ROOT_URLCONF`` 、 ``SECRET_KEY`` 被PyWebIO设置，不可以手动指定
+        其中 ``DEBUG`` 、 ``ALLOWED_HOSTS`` 、 ``ROOT_URLCONF`` 、 ``SECRET_KEY`` 被PyWebIO设置，无法在 ``django_options`` 中指定
     """
     global urlpatterns
 

pywebio/platform/flask.py

@@ -122,9 +122,9 @@ def start_server(applications, port=8080, host='localhost',
     """启动一个 Flask server 将PyWebIO应用作为Web服务提供。
 
     :param list/dict/callable applications: PyWebIO应用. 格式同 :func:`pywebio.platform.start_server` 的 ``applications`` 参数
-    :param int port: server bind port. set ``0`` to find a free port number to use
-    :param str host: server bind host. ``host`` may be either an IP address or hostname.
-       set empty string or `None` to listen on all available interfaces.
+    :param int port: 服务监听的端口。设置为 ``0`` 时，表示自动选择可用端口。
+    :param str host: 服务绑定的地址。 ``host`` 可以是IP地址或者为hostname。如果为hostname，服务会监听所有与该hostname关联的IP地址。
+        通过设置 ``host`` 为空字符串或 ``None`` 来将服务绑定到所有可用的地址上。
     :param list allowed_origins: 除当前域名外，服务器还允许的请求的来源列表。
         来源包含协议和域名和端口部分，允许使用 Unix shell 风格的匹配模式:
 
@@ -145,8 +145,8 @@ def start_server(applications, port=8080, host='localhost',
     :param int session_expire_seconds: 会话过期时间。若 session_expire_seconds 秒内没有收到客户端的请求，则认为会话过期。
     :param int session_cleanup_interval: 会话清理间隔。
     :param bool debug: Flask debug mode
-    :param flask_options: Additional keyword arguments passed to the constructor of ``flask.Flask.run``.
-        ref: https://flask.palletsprojects.com/en/1.1.x/api/?highlight=flask%20run#flask.Flask.run
+    :param flask_options: 传递给 ``flask.Flask.run`` 函数的额外的关键字参数
+        可设置项参考: https://flask.palletsprojects.com/en/1.1.x/api/#flask.Flask.run
     """
     if not host:
         host = '0.0.0.0'

pywebio/platform/tornado.py

@@ -180,11 +180,10 @@ def start_server(applications, port=0, host='', debug=False,
        可以通过 ``app`` URL参数选择要运行的任务，默认使用运行 ``index`` 任务函数，当 ``index`` 任务不存在时，PyWebIO会提供一个默认的索引页作为主页。
 
        任务函数为协程函数时，使用 :ref:`基于协程的会话实现 <coroutine_based_session>` ；任务函数为普通函数时，使用基于线程的会话实现。
-    :param int port: server bind port. set ``0`` to find a free port number to use
-    :param str host: server bind host. ``host`` may be either an IP address or hostname.  If it's a hostname,
-        the server will listen on all IP addresses associated with the name.
-        set empty string or `None` to listen on all available interfaces.
-    :param bool debug: Tornado debug mode
+    :param int port: 服务监听的端口。设置为 ``0`` 时，表示自动选择可用端口。
+    :param str host: 服务绑定的地址。 ``host`` 可以是IP地址或者为hostname。如果为hostname，服务会监听所有与该hostname关联的IP地址。
+       通过设置 ``host`` 为空字符串或 ``None`` 来将服务绑定到所有可用的地址上。
+    :param bool debug: Tornado Server是否开启debug模式
     :param list allowed_origins: 除当前域名外，服务器还允许的请求的来源列表。
         来源包含协议和域名和端口部分，允许使用 Unix shell 风格的匹配模式:
 
@@ -196,17 +195,15 @@ def start_server(applications, port=0, host='', debug=False,
         比如 ``https://*.example.com`` 、 ``*://*.example.com``
     :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 int websocket_max_message_size: Max bytes of a message which Tornado can accept.
-        Messages larger than the ``websocket_max_message_size`` (default 10MiB) will not be accepted.
-    :param int websocket_ping_interval: If set to a number, all websockets will be pinged every n seconds.
-        This can help keep the connection alive through certain proxy servers which close idle connections,
-        and it can detect if the websocket has failed without being properly closed.
-    :param int websocket_ping_timeout: If the ping interval is set, and the server doesn’t receive a ‘pong’
-        in this many seconds, it will close the websocket. The default is three times the ping interval,
-        with a minimum of 30 seconds. Ignored if ``websocket_ping_interval`` is not set.
-    :param tornado_app_settings: Additional keyword arguments passed to the constructor of ``tornado.web.Application``.
-        ref: https://www.tornadoweb.org/en/stable/web.html#tornado.web.Application.settings
+    :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`` 的三倍。
+    :param tornado_app_settings: 传递给 ``tornado.web.Application`` 构造函数的额外的关键字参数
+        可设置项参考: https://www.tornadoweb.org/en/stable/web.html#tornado.web.Application.settings
     """
     kwargs = locals()
     global _ioloop

pywebio/session/__init__.py

@@ -107,7 +107,9 @@ def check_session_impl(session_type):
 
 
 def chose_impl(gen_func):
-    """根据当前会话实现来将 gen_func 转化为协程对象或直接以函数运行"""
+    """
+    装饰器，使用chose_impl对gen_func进行装饰后，gen_func() 操作将根据当前会话实现 返回协程对象 或 直接运行函数体
+    """
 
     @wraps(gen_func)
     def inner(*args, **kwargs):