浏览代码

doc update

wangweimin 4 年之前
父节点
当前提交
44ddab3e50
共有 9 个文件被更改,包括 85 次插入82 次删除
  1. 4 5
      README.md
  2. 1 1
      demos/chat_room.py
  3. 1 1
      docs/conf.py
  4. 4 4
      docs/guide.rst
  5. 5 5
      docs/index.rst
  6. 1 1
      pywebio/__init__.py
  7. 1 2
      pywebio/__version__.py
  8. 67 61
      pywebio/output.py
  9. 1 2
      test/13.misc.py

+ 4 - 5
README.md

@@ -52,16 +52,15 @@ PyWebIO还可以方便地整合进现有的Web服务,让你不需要编写HTML
 
 ## Install
 
-PyPi安装:
+稳定版安装:
 
 ```bash
 pip3 install -U pywebio
 ```
 
-目前PyWebIO处于快速开发迭代中,PyPi上的包更新可能滞后,建议使用源码安装:
-
+开发版安装:
 ```bash
-pip3 install -U https://code.aliyun.com/wang0618/pywebio/repository/archive.zip
+pip3 install -U --force-reinstall https://code.aliyun.com/wang0618/pywebio/repository/archive.zip
 ```
 
 **系统要求**: PyWebIO要求 Python 版本在 3.5.2 及以上
@@ -106,7 +105,7 @@ if __name__ == '__main__':
 
 **作为Web服务提供**
 
-上文对使用PyWebIO进行改造的程序,运行模式还是脚本,程序计算完毕后立刻退出。可以使用 [`pywebio.start_server()`](https://pywebio.readthedocs.io/zh_CN/latest/platform.html#pywebio.platform.start_server) 将 `bmi()` 函数作为Web服务提供:
+上文对使用PyWebIO进行改造的程序,运行模式还是脚本,程序计算完毕后立刻退出。可以使用 [`pywebio.start_server()`](https://pywebio.readthedocs.io/zh_CN/latest/platform.html#pywebio.platform.tornado.start_server) 将 `bmi()` 函数作为Web服务提供:
 
 ```python
 from pywebio import start_server

+ 1 - 1
demos/chat_room.py

@@ -45,7 +45,7 @@ async def main():
 
     set_env(title="PyWebIO Chat Room")
 
-    put_markdown("##PyWebIO聊天室\n欢迎来到聊天室,你可以和当前所有在线的人聊天。"
+    put_markdown("##PyWebIO聊天室\n欢迎来到聊天室,你可以和当前所有在线的人聊天。你可以在浏览器的多个标签页中打开本页面来测试聊天效果。"
     "本应用使用不到80行代码实现,源代码[链接](https://github.com/wang0618/PyWebIO/blob/dev/demos/chat_room.py)", lstrip=True)
 
     msg_box = output()

+ 1 - 1
docs/conf.py

@@ -19,7 +19,7 @@ version = release = pywebio.__version__
 # -- Project information -----------------------------------------------------
 
 project = 'PyWebIO'
-copyright = '2020, WangWeimin'
+copyright = 'WangWeimin'
 author = 'WangWeimin'
 
 # -- General configuration ---------------------------------------------------

+ 4 - 4
docs/guide.rst

@@ -8,7 +8,7 @@ User's guide
 ``file_upload`` 等函数在浏览器上显示不同表单来接收用户的输入。此外PyWebIO中还提供了点击事件、布局等支持,让你可以使用最少的代码完成与用户的交互,
 并尽可能提供良好的用户体验。
 
-本篇使用指南从几个方面对PyWebIO的使用进行介绍,覆盖了PyWebIO的绝大部分特性。大部分示例代码的右上方都有一个Demo链接,点击后可以在线预览代码的运行效果。
+本篇使用指南从几个方面对PyWebIO的使用进行介绍,覆盖了PyWebIO的绝大部分特性。本文档中大部分示例代码的右上方都有一个Demo链接,点击后可以在线预览代码的运行效果。
 
 输入
 ------------
@@ -595,14 +595,14 @@ Server模式与Script模式
 ------------------------------------
 
 在 :ref:`Hello, world <hello_word>` 一节中,已经知道,PyWebIO支持在普通的脚本中调用和使用
-`start_server() <pywebio.platform.start_server>` 启动一个Web服务两种模式。
+`start_server() <pywebio.platform.tornado.start_server>` 启动一个Web服务两种模式。
 
 **Server模式**
 
 在Server模式下,PyWebIO会启动一个Web服务来持续性地提供服务。需要提供一个任务函数(类似于Web开发中的视图函数),当用户访问服务地址时,PyWebIO会开启一个新会话并运行任务函数。
 
-使用 `start_server() <pywebio.platform.start_server>` 来启动PyWebIO的Server模式, `start_server() <pywebio.platform.start_server>` 除了接收一个函数作为任务函数外,
-还支持传入函数列表或字典,从而使一个PyWebIO Server下可以有多个不同功能的服务,用户可以通过指定URL参数选择访问不同的服务,服务之间可以通过 `go_app() <pywebio.session.go_app>` 进行跳转,更多内容见函数文档。
+使用 `start_server() <pywebio.platform.tornado.start_server>` 来启动PyWebIO的Server模式, `start_server() <pywebio.platform.tornado.start_server>` 除了接收一个函数作为任务函数外,
+还支持传入函数列表或字典,从而使一个PyWebIO Server下可以有多个不同功能的服务,服务之间可以通过 `go_app() <pywebio.session.go_app>` 进行跳转,详细内容见函数文档。
 
 .. attention::
 

+ 5 - 5
docs/index.rst

@@ -3,7 +3,7 @@ PyWebIO
 
 PyWebIO提供了一系列命令式的交互函数来在浏览器上获取用户输入和进行输出,将浏览器变成了一个“富文本终端”,可以用于构建简单的Web应用或基于浏览器的GUI应用。
 使用PyWebIO,开发者能像编写终端脚本一样(基于input和print进行交互)来编写应用,无需具备HTML和JS的相关知识;
-PyWebIO还可以方便地整合进现有的Web框架。非常适合在短时间内快速构建对UI要求不高的应用。
+PyWebIO还可以方便地整合进现有的Web框架。非常适合快速构建对UI要求不高的应用。
 
 
 特性
@@ -19,13 +19,13 @@ PyWebIO还可以方便地整合进现有的Web框架。非常适合在短时间
 Install
 ------------
 
-PyPi安装::
+稳定版安装::
 
    pip3 install -U pywebio
 
-目前PyWebIO处于快速迭代时期,PyPi上的包更新可能滞后,建议使用源码安装::
+开发版安装::
 
-    pip3 install -U https://code.aliyun.com/wang0618/pywebio/repository/archive.zip
+    pip3 install -U --force-reinstall https://code.aliyun.com/wang0618/pywebio/repository/archive.zip
 
 **系统要求**: PyWebIO要求 Python 版本在 3.5.2 及以上
 
@@ -64,7 +64,7 @@ Hello, world
    :width: 450px
    :align: center
 
-将上面代码最后一行对 ``bmi()`` 的直接调用改为使用 `pywebio.start_server(bmi, port=80) <pywebio.platform.start_server>` 便可以在80端口提供 ``bmi()`` 服务( :demo_host:`在线Demo </?pywebio_api=bmi>` )。
+将上面代码最后一行对 ``bmi()`` 的直接调用改为使用 `pywebio.start_server(bmi, port=80) <pywebio.platform.tornado.start_server>` 便可以在80端口提供 ``bmi()`` 服务( :demo_host:`在线Demo </?pywebio_api=bmi>` )。
 
 将 ``bmi()`` 服务整合到现有的Web框架请参考 :ref:`与Web框架集成 <integration_web_framework>`
 

+ 1 - 1
pywebio/__init__.py

@@ -6,7 +6,7 @@ from .exceptions import SessionException, SessionClosedException, SessionNotFoun
 from .utils import STATIC_PATH
 
 from .__version__ import __description__, __url__, __version__
-from .__version__ import __author__, __author_email__, __license__, __copyright__
+from .__version__ import __author__, __author_email__, __license__
 
 from .platform.bokeh import try_install_bokeh_hook
 

+ 1 - 2
pywebio/__version__.py

@@ -5,5 +5,4 @@ __version__ = "0.3.0"
 __version_info__ = (0, 3, 0, 0)
 __author__ = 'WangWeimin'
 __author_email__ = 'wang0.618@qq.com'
-__license__ = 'MIT'
-__copyright__ = 'Copyright 2020 WangWeimin'
+__license__ = 'MIT'

+ 67 - 61
pywebio/output.py

@@ -4,51 +4,72 @@ r"""输出内容到用户浏览器
 
 函数清单
 --------------
-
-* 输出域Scope
-
-    * `set_scope` : 创建一个新的scope.
-    * `get_scope` : 获取当前运行时scope栈中的scope名
-    * `clear` : 清空scope内容
-    * `remove` : 移除Scope
-    * `scroll_to` : 将页面滚动到 scope Scope处
-    * `use_scope` : 开启/进入输出域
-
-* 内容输出
-
-    * `put_text` : 输出文本
-    * `put_markdown` : 输出Markdown
-    * `put_html` : 输出Html
-    * `put_link` : 输出链接
-    * `put_processbar` : 输出进度条
-    * `set_processbar` : 设置进度条进度
-    * `put_loading` : 输出加载提示
-    * `put_code` : 输出代码块
-    * `put_table` : 输出表格
-    * `span` : 用于在 `put_table()` 和 `put_grid()` 中设置内容跨单元格
-    * `put_buttons` : 输出一组按钮,并绑定点击事件
-    * `put_image` : 输出图片
-    * `put_file` : 显示一个文件下载链接
-    * `put_collapse` : 输出可折叠的内容
-    * `put_scrollable` : 固定高度内容输出区域,内容超出则显示滚动条
-    * `put_widget` : 输出自定义的控件
-
-* 其他交互
-
-    * `toast` : 显示一条通知消息
-    * `popup` : 显示弹窗
-    * `close_popup` : 关闭正在显示的弹窗
-
-* 布局与样式
-
-    * `put_row` : 使用行布局输出内容
-    * `put_column` : 使用列布局输出内容
-    * `put_grid` : 使用网格布局输出内容
-    * `style` : 自定义输出内容的css样式
-
-* 其他
-
-    * `output` : 内容占位符
+..
+  Use https://www.tablesgenerator.com/text_tables to generate/update below table
+
++-------------+------------------+---------------------------------------------------------+
+|             | **函数**         | **简介**                                                |
++-------------+------------------+---------------------------------------------------------+
+| 输出域Scope | `set_scope`      | 创建一个新的scope.                                      |
+|             +------------------+---------------------------------------------------------+
+|             | `get_scope`      | 获取当前运行时scope栈中的scope名                        |
+|             +------------------+---------------------------------------------------------+
+|             | `clear`          | 清空scope内容                                           |
+|             +------------------+---------------------------------------------------------+
+|             | `remove`         | 移除Scope                                               |
+|             +------------------+---------------------------------------------------------+
+|             | `scroll_to`      | 将页面滚动到 scope Scope处                              |
+|             +------------------+---------------------------------------------------------+
+|             | `use_scope`      | 开启/进入输出域                                         |
++-------------+------------------+---------------------------------------------------------+
+| 内容输出    | `put_text`       | 输出文本                                                |
+|             +------------------+---------------------------------------------------------+
+|             | `put_markdown`   | 输出Markdown                                            |
+|             +------------------+---------------------------------------------------------+
+|             | `put_html`       | 输出Html                                                |
+|             +------------------+---------------------------------------------------------+
+|             | `put_link`       | 输出链接                                                |
+|             +------------------+---------------------------------------------------------+
+|             | `put_processbar` | 输出进度条                                              |
+|             +------------------+---------------------------------------------------------+
+|             | `set_processbar` | 设置进度条进度                                          |
+|             +------------------+---------------------------------------------------------+
+|             | `put_loading`    | 输出加载提示                                            |
+|             +------------------+---------------------------------------------------------+
+|             | `put_code`       | 输出代码块                                              |
+|             +------------------+---------------------------------------------------------+
+|             | `put_table`      | 输出表格                                                |
+|             +------------------+---------------------------------------------------------+
+|             | `put_buttons`    | 输出一组按钮,并绑定点击事件                            |
+|             +------------------+---------------------------------------------------------+
+|             | `put_image`      | 输出图片                                                |
+|             +------------------+---------------------------------------------------------+
+|             | `put_file`       | 显示一个文件下载链接                                    |
+|             +------------------+---------------------------------------------------------+
+|             | `put_collapse`   | 输出可折叠的内容                                        |
+|             +------------------+---------------------------------------------------------+
+|             | `put_scrollable` | 固定高度内容输出区域,内容超出则显示滚动条              |
+|             +------------------+---------------------------------------------------------+
+|             | `put_widget`     | 输出自定义的控件                                        |
++-------------+------------------+---------------------------------------------------------+
+| 其他交互    | `toast`          | 显示一条通知消息                                        |
+|             +------------------+---------------------------------------------------------+
+|             | `popup`          | 显示弹窗                                                |
+|             +------------------+---------------------------------------------------------+
+|             | `close_popup`    | 关闭正在显示的弹窗                                      |
++-------------+------------------+---------------------------------------------------------+
+| 布局与样式  | `put_row`        | 使用行布局输出内容                                      |
+|             +------------------+---------------------------------------------------------+
+|             | `put_column`     | 使用列布局输出内容                                      |
+|             +------------------+---------------------------------------------------------+
+|             | `put_grid`       | 使用网格布局输出内容                                    |
+|             +------------------+---------------------------------------------------------+
+|             | `span`           | 在 `put_table()` 和 `put_grid()` 中设置内容跨单元格     |
+|             +------------------+---------------------------------------------------------+
+|             | `style`          | 自定义输出内容的css样式                                 |
++-------------+------------------+---------------------------------------------------------+
+| 其他        | `output`         | 内容占位符                                              |
++-------------+------------------+---------------------------------------------------------+
 
 
 输出域Scope
@@ -72,7 +93,6 @@ r"""输出内容到用户浏览器
 .. autofunction:: put_code
 .. autofunction:: put_table
 .. autofunction:: span
-.. autofunction:: table_cell_buttons
 .. autofunction:: put_buttons
 .. autofunction:: put_image
 .. autofunction:: put_file
@@ -121,7 +141,7 @@ logger = logging.getLogger(__name__)
 
 __all__ = ['Position', 'remove', 'scroll_to',
            'put_text', 'put_html', 'put_code', 'put_markdown', 'use_scope', 'set_scope', 'clear', 'remove',
-           'put_table', 'table_cell_buttons', 'put_buttons', 'put_image', 'put_file', 'PopupSize', 'popup',
+           'put_table', 'put_buttons', 'put_image', 'put_file', 'PopupSize', 'popup',
            'close_popup', 'put_widget', 'put_collapse', 'put_link', 'put_scrollable', 'style', 'put_column',
            'put_row', 'put_grid', 'column', 'row', 'grid', 'span', 'put_processbar', 'set_processbar', 'put_loading',
            'output', 'toast', 'get_scope']
@@ -516,20 +536,6 @@ def _format_button(buttons):
     return btns
 
 
-def table_cell_buttons(buttons, onclick, **callback_options) -> Output:
-    """
-    在表格中显示一组按钮
-
-    :param str buttons, onclick, save: 与 `put_buttons` 函数的同名参数含义一致
-
-    .. deprecated:: 0.3
-       Use :func:`put_buttons()` instead
-    """
-    logger.warning("pywebio.output.table_cell_buttons() is deprecated in version 0.3 and will be removed in 1.0, "
-                   "use pywebio.output.put_buttons() instead.")
-    return put_buttons(buttons, onclick, small=True, **callback_options)
-
-
 def put_buttons(buttons, onclick, small=None, link_style=False, scope=Scope.Current, position=OutputPosition.BOTTOM,
                 **callback_options) -> Output:
     """

+ 1 - 2
test/13.misc.py

@@ -44,10 +44,9 @@ def target():
     except Exception:
         pass
 
-    # test deprecated api
     put_table([
         ['Idx', 'Actions'],
-        ['1', table_cell_buttons(['edit', 'delete'], onclick=lambda _: None)],
+        ['1', put_buttons(['edit', 'delete'], onclick=lambda _: None)],
     ])
 
     popup('title', 'text content')