update doc

pywebio/output.py

@@ -48,6 +48,7 @@ TOP = 'top'
 MIDDLE = 'middle'
 BOTTOM = 'bottom'
 
+
 def set_title(title):
     r"""设置页面标题"""
     send_msg('output_ctl', dict(title=title))
@@ -107,6 +108,7 @@ def scroll_to(anchor, position=TOP):
 
     :param str anchor: 锚点名
     :param str position: 将锚点置于屏幕可视区域的位置。可用值：
+
        * ``TOP`` : 滚动页面，让锚点位于屏幕可视区域顶部
        * ``MIDDLE`` : 滚动页面，让锚点位于屏幕可视区域中间
        * ``BOTTOM`` : 滚动页面，让锚点位于屏幕可视区域底部
@@ -183,7 +185,6 @@ def put_markdown(mdcontent, strip_indent=0, lstrip=False, anchor=None, before=No
     """
     输出Markdown内容。
 
-
     :param str mdcontent: Markdown文本
     :param int strip_indent: 对于每一行，若前 ``strip_indent`` 个字符都为空格，则将其去除
     :param bool lstrip: 是否去除每一行开始的空白符

pywebio/platform/__init__.py

@@ -1,13 +1,20 @@
 r"""
-platform 模块为PyWebIO提供了对不同Web框架的支持。
-
-你可以启动使用不同Web框架的Server，或者获得整合进现有Web框架的必要数据。
+``platform`` 模块为PyWebIO提供了对不同Web框架的支持。
 
+Tornado相关
+--------------
 
 .. autofunction:: start_server
-.. autofunction:: pywebio.platform.flask.webio_view
 .. autofunction:: pywebio.platform.tornado.webio_handler
 
+Flask相关
+--------------
+
+.. autofunction:: pywebio.platform.flask.webio_view
+.. autofunction:: pywebio.platform.flask.run_event_loop
+.. autofunction:: pywebio.platform.flask.start_server
+
+
 """
 
 from . import tornado

pywebio/platform/flask.py

@@ -187,7 +187,8 @@ def start_server(target, port=8080, host='localhost',
                  disable_asyncio=False,
                  session_expire_seconds=DEFAULT_SESSION_EXPIRE_SECONDS,
                  debug=False, **flask_options):
-    """
+    """启动一个 Flask server 来运行PyWebIO的 ``target`` 服务
+
     :param target: task function. It's a coroutine function is use CoroutineBasedSession or
         a simple function is use ThreadBasedSession.
     :param port: server bind port. set ``0`` to find a free port number to use
@@ -201,9 +202,8 @@ def start_server(target, port=8080, host='localhost',
         若程序中没有使用到asyncio中的异步函数，可以开启此选项来避免不必要的资源浪费
     :param session_expire_seconds: 会话过期时间。若 session_expire_seconds 秒内没有收到客户端的请求，则认为会话过期。
     :param debug: Flask debug mode
-    :param flask_options: Additional keyword arguments passed to the constructor of ``tornado.web.Application``.
-        ref: https://www.tornadoweb.org/en/stable/web.html#tornado.web.Application.settings
-    :return:
+    :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
     """
 
     app = Flask(__name__)

pywebio/platform/tornado.py

@@ -14,7 +14,7 @@ import tornado.websocket
 from tornado.web import StaticFileHandler
 from tornado.websocket import WebSocketHandler
 from ..session import CoroutineBasedSession, ThreadBasedSession, get_session_implement, ScriptModeSession, \
-    set_session_implement_for_target
+    set_session_implement_for_target, AbstractSession
 from ..utils import get_free_port, wait_host_port, STATIC_PATH
 
 logger = logging.getLogger(__name__)
@@ -57,7 +57,7 @@ def _webio_handler(target, check_origin_func=_is_same_site):
             # Non-None enables compression with default options.
             return {}
 
-        def send_msg_to_client(self, session: CoroutineBasedSession):
+        def send_msg_to_client(self, session: AbstractSession):
             for msg in session.get_task_commands():
                 self.write_message(json.dumps(msg))
 
@@ -168,7 +168,6 @@ def start_server(target, port=0, host='', debug=False,
         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
-    :return:
     """
     kwargs = locals()
 

pywebio/session/__init__.py

@@ -74,7 +74,7 @@ def check_session_impl(session_type):
 
 @check_session_impl(CoroutineBasedSession)
 def run_async(coro_obj):
-    """异步运行协程对象。协程中依然可以调用 PyWebIO 交互函数。 仅能在 CoroutineBasedSession 会话上下文中调用
+    """异步运行协程对象。协程中依然可以调用 PyWebIO 交互函数。 仅能在基于协程的会话上下文中调用
 
     :param coro_obj: 协程对象
     :return: An instance of  `TaskHandle <pywebio.session.coroutinebased.TaskHandle>` is returned, which can be used later to close the task.
@@ -84,7 +84,7 @@ def run_async(coro_obj):
 
 @check_session_impl(CoroutineBasedSession)
 async def run_asyncio_coroutine(coro_obj):
-    """若会话线程和运行事件的线程不是同一个线程，需要用 run_asyncio_coroutine 来运行asyncio中的协程
+    """若会话线程和运行事件的线程不是同一个线程，需要用 run_asyncio_coroutine 来运行asyncio中的协程。 仅能在基于协程的会话上下文中调用
 
     :param coro_obj: 协程对象
     """
@@ -93,7 +93,7 @@ async def run_asyncio_coroutine(coro_obj):
 
 @check_session_impl(ThreadBasedSession)
 def register_thread(thread: threading.Thread):
-    """注册线程，以便在线程内调用 PyWebIO 交互函数。仅能在 ThreadBasedSession 会话上下文中调用
+    """注册线程，以便在线程内调用 PyWebIO 交互函数。仅能在基于线程的会话上下文中调用
 
     :param threading.Thread thread: 线程对象
     """

pywebio/session/coroutinebased.py

@@ -69,7 +69,7 @@ class CoroutineBasedSession(AbstractSession):
         self._on_session_close = on_session_close or (lambda: None)
         self.unhandled_task_msgs = []
 
-        self.coros = {}  # coro_task_id -> coro
+        self.coros = {}  # coro_task_id -> Task()
 
         self._closed = False
         self._not_closed_coro_cnt = 1  # 当前会话未结束运行的协程数量。当 self._not_closed_coro_cnt == 0 时，会话结束。