add overview script

pywebio/demos/overview-zh.py

@@ -0,0 +1,374 @@
+"""
+使用PyWebIO来介绍PyWebIO的各个特性
+"""
+
+from pywebio.interact import *
+from pywebio.ioloop import start_ioloop
+from pywebio.output import *
+import asyncio
+from datetime import datetime
+
+
+async def other(data, save):
+    text_print("You click %s button" % data)
+    text_print("Button save:%s" % save)
+
+    res = await input("You click %s button" % data)
+    text_print(res)
+
+
+async def feature_overview():
+    set_auto_scroll_bottom(False)
+    set_output_fixed_height(False)
+    set_title("PyWebIO 特性一览")
+
+    put_markdown("""# PyWebIO 特性一览
+    你现在看到和即将看到的内容就是使用PyWebIO来创建的，"用自己来介绍自己" 是不是很有趣 😄(下文有彩蛋)
+
+    ## What is PyWebIO
+    PyWebIO，一个用于在浏览器上进行输入输出的工具库。能够将原有的通过终端交互的脚本快速服务化，供其他人在网络通过浏览器使用；PyWebIO还可以方便地整合进现有的web服务，非常适合于构建后端服务的功能原型。
+
+    特点：
+    - 使用同步而不是基于回调的方式获取输入，无需在各个步骤之间保存状态，直观、方便
+    - 代码侵入性小
+    - 支持并发请求
+    - 支持状态恢复
+    - 支持整合到现有的web服务，目前支持与Tronado、Flask、Django的集成
+
+    对上面的内容一脸黑人问号，没关系，下面是一些PyWebIO是什么，以及能够做什么的直观的例子
+
+    ### 基本输入
+    首先是一些基本类型的输入
+
+    #### 文本输入
+    ```python
+    age = await input("How old are you?", type=NUMBER)  # type can be in {TEXT, NUMBER, PASSWORD}
+    ```
+    这样一行代码的效果如下，浏览器会弹出一个文本输入框来获取输入，在你提交表单之前，你的程序不会往下运行
+    """, lstrip=True)
+    age = await input("How old are you?", type=NUMBER)
+    text_print("你的年龄是：%s" % age)
+
+    put_markdown("""#### 下拉选择框
+    ```python
+    gift = await select('Which gift you want?', ['keyboard', 'ipad'])
+    ```
+    """, lstrip=True)
+    gift = await select('Which gift you want?', ['keyboard', 'ipad'])
+    text_print("%s sounds great！" % gift)
+
+    put_markdown("""#### CheckBox
+    ```python
+    agree = await select("用户协议", type=CHECKBOX, options=['I agree to terms and conditions'])
+    ```
+    """, lstrip=True)
+    agree = await select("用户协议", type=CHECKBOX,
+                         options=[{'value': 'agree', 'label': 'I agree to terms and conditions'}])
+    text_print("You %s to terms and conditions" % ('agree' if agree == 'agree' else 'disagree'))
+
+    put_markdown("""#### Text Area
+    ```python
+    text = await textarea('Text Area', rows='3', placeholder='Some text')
+    ```
+    """, lstrip=True)
+    text = await textarea('Text Area', rows='3', placeholder='Some text')
+    text_print('Your input:%s' % text)
+
+    put_markdown("""textarea还支持使用 <a href="https://codemirror.net/" target="_blank">Codemirror</a>实现代码风格的编辑区，只需使用`codemirror`参数传入Codemirror支持的选项：
+    ```python
+    code = await textarea('Code', codemirror={
+        'mode': "python",  # 代码语言
+        'theme': 'darcula',  # 使用darcula主题
+    }, value='import something\n# Write your python code')
+    ```
+    """, lstrip=True)
+    code = await textarea('Code', codemirror={
+        'mode': "python",  # 代码语言
+        'theme': 'darcula',  # 使用darcula主题
+    }, value='import something\n# Write your python code')
+    put_markdown('Your code:\n```python\n%s\n```' % code)
+
+    put_markdown("""#### Actions
+    ```python
+    choice = await actions("What do you want in next?", ["Go homepage", "Quit"])
+    ```
+    """, lstrip=True)
+    choice = await actions("What do you want in next?", ["Go homepage", "Quit"])
+    text_print("You choose %s" % choice)
+
+    put_markdown("""#### 文件上传
+    ```python
+    img = await file_upload("Select a image:(accept jpg、png、gif file)", accept=[".jpg", ".png", ".gif"])
+    ```
+    """, lstrip=True)
+    img = await file_upload("Select a image:(accept jpg、png、gif file)", accept=[".jpg", ".png", ".gif"])
+    text_print("Image name: %s\nImage size: %d KB" % (img['filename'], len(img['content']) / 1000))
+
+    put_markdown("""### 输入选项
+    输入函数可指定的参数非常丰富，就比如：
+    ```python
+    await input('Help Text', type=TEXT, help_text='This is help text')
+    ```
+    """, lstrip=True)
+    await input('Help Text', type=TEXT, help_text='This is help text')
+
+    put_markdown("""```python
+    await input('Placeholder', type=TEXT, placeholder='This is placeholder')
+    ```
+    """, lstrip=True)
+    await input('Placeholder', type=TEXT, placeholder='This is placeholder')
+
+    put_markdown("""```python
+    await input('Readonly', type=TEXT, readonly=True, value="You can't change me")
+    ```
+    """, lstrip=True)
+    await input('Readonly', type=TEXT, readonly=True, value="You can't change me")
+
+    put_markdown("""我们可以为输入指定校验函数，校验函数校验通过时返回None，否则返回错误消息：
+    ```python
+    def check_age(p):  # 检验函数校验通过时返回None，否则返回错误消息
+        if p < 10:
+            return 'Too young!!'
+        if p > 60:
+            return 'Too old!!'
+
+    age = await input("How old are you?", type=NUMBER, valid_func=check_age)
+    ```
+    """, strip_indent=4)
+
+    def check_age(p):  # 检验函数校验通过时返回None，否则返回错误消息
+        if p < 18:
+            return 'Too young!!'
+        if p > 60:
+            return 'Too old!!'
+
+    age = await input("How old are you?", type=NUMBER, valid_func=check_age, help_text='你可以输入一些不合法的数字(比如10)来查看错误提示的效果')
+
+    put_markdown("""### 输入组
+    PyWebIO还支持一组输入, 返回结果为一个字典。input_group接受前面的单项输入组成的列表作为参数，同时为了在返回的结果中区别出每一项输入，还需要在单项输入函数中传入`name`参数，input_group返回的字典就是以单项输入函数中的`name`作为键。
+    ```python
+    data = await input_group("Basic info",[
+      input('Input your name', name='name'), 
+      input('Repeat your age', name='age', type=NUMBER, valid_func=check_age)
+    ], valid_func=check_form)
+    print(data['name'], data['age'])
+    ```
+    输入组中同样支持设置校验函数，其接受整个表单数据作为参数：
+    ```python
+    def check_form(data):  # 检验函数校验通过时返回None，否则返回 (input name,错误消息)
+        if len(data['name']) > 6:
+            return ('name', '名字太长！')
+        if data['age'] <= 0:
+            return ('age', '年龄不能为负数！')
+    ```
+    """, strip_indent=4)
+
+    def check_form(data):  # 检验函数校验通过时返回None，否则返回 (input name,错误消息)
+        """返回 (name, error_msg) 表示输入错误"""  # todo 也可返回单独error_msg表示错误消息
+        if len(data['name']) > 6:
+            return ('name', '名字太长！')
+        if data['age'] <= 0:
+            return ('age', '年龄不能为负数！')
+
+    data = await input_group("Basic info", [
+        input('Input your name', name='name'),
+        input('Repeat your age', name='age', type=NUMBER, valid_func=check_age)
+    ], valid_func=check_form)
+    text_print('Your name:%s\nYour age:%d' % (data['name'], data['age']))
+
+    put_markdown("""### 输出
+    说完了输入，我们再说一下输出，PyWebIO也提供了一些便捷函数来输出表格，链接等格式
+    #### 基本输出
+    首先是文本输出：
+    ```python
+    # 文本输出
+    text_print("Hello world!")
+
+    # 表格输出
+    put_table([
+        ['商品', '价格'],
+        ['苹果', '5.5'],
+        ['香蕉', '7'],
+    ])
+
+    # Markdown输出
+    put_markdown('~~删除线~~')
+
+    # 文件输出
+    put_file('hello_word.txt', b'hello word!')
+    ```
+    """, strip_indent=4)
+    text_print("Hello world!")
+    put_table([
+        ['商品', '价格'],
+        ['苹果', '5.5'],
+        ['香蕉', '7'],
+    ])
+    put_markdown('~~删除线~~')
+    put_file('hello_word.txt', b'hello word!')
+
+    put_markdown("""#### 输出事件
+    通过刚刚的体验，相比聪明的你已经大概了解：PyWebIO可以通过调用不同的输入函数在浏览器中获取用户的输入，并且通过浏览器展示程序的输出。并且一旦调用 `await some_input_func()`，在表单提交之前程序将不会往下运行。
+    这种模式已经可以满足绝大部分的交互需求了，但是在某些场景下还是显得不太方便，就比如你通过表格输出了用户的登陆日志，用户可能希望对表格的某些行进行编辑或者对表格什么也不做，这个时候，你可能会使用一个`while`循环，并且在循环中调用`choice = await actions("What do you want in next?", ["Edit some rows", "Back"])`，如果用户选择了"Edit some rows"，你还要接着询问用户希望编辑哪些行......，emm，想想就头大。
+    幸运的是，PyWebIO还支持输出可以绑定事件的按钮控件，非常适合上述场景的需求。
+    上述场景通过按钮控件实现如下：
+    ```python
+    def edit_row(choice, save):
+        text_print("You click %s button ar row %s" % (choice, save))
+
+    put_table([
+        ['Idx', 'Actions'],
+        [1, td_buttons(['edit', 'delete'], onclick=edit_row, save=1)],
+        [2, td_buttons(['edit', 'delete'], onclick=edit_row, save=2)],
+        [3, td_buttons(['edit', 'delete'], onclick=edit_row, save=3)],
+    ])
+    ```
+    """, strip_indent=4)
+
+    def edit_row(choice, save):
+        text_print("You click %s button ar row %s" % (choice, save))
+
+    put_table([
+        ['Idx', 'Actions'],
+        [1, td_buttons(['edit', 'delete'], onclick=edit_row, save=1)],
+        [2, td_buttons(['edit', 'delete'], onclick=edit_row, save=2)],
+        [3, td_buttons(['edit', 'delete'], onclick=edit_row, save=3)],
+    ])
+    put_markdown("""这样，你不必等待用户点击某个按钮，而是可以继续往下运行程序，当用户点击了某行中的按钮时，程序会自动调用相应的处理函数\n
+    当然，PyWebIO还支持单独的按钮控件：
+    ```python
+    def btn_click(btn_val, save):
+        text_print("You click btn_val button" % btn_val)
+    buttons(['A', 'B', 'C'], onclick=btn_click)
+    ```
+    """, strip_indent=4)
+
+    def btn_click(btn_val, save):
+        text_print("You click %s button" % btn_val)
+
+    buttons(['A', 'B', 'C'], onclick=btn_click)
+
+    await actions('', ['继续教程'])
+
+    put_markdown("""#### 锚点
+    你可以调用`set_anchor(name)`对当前输出位置进行标记，这一调用不会在用户浏览器上产生任何输出，需要与下面几个函数结合使用：
+    调用`set_anchor(name)`可以清除anchor锚点之前输出的内容
+    调用`clear_after(name)`可以清除anchor锚点之后输出的内容
+    调用`clear_range(start_anchor, end_ancher)`可以清除start_anchor到end_ancher锚点之间的内容
+    调用`scroll_to(name)`可以将页面滚动到anchor锚点处
+    """, strip_indent=4)
+
+    set_anchor('anchor')
+    put_markdown("""这个例子展示了锚点的一个用法：
+    ```python
+    import asyncio
+    from datetime import datetime
+
+    set_anchor('counter')
+    for i in range(15, -1, -1):
+        clear_after('counter')
+        text_print('倒计时:%s' % i)
+        await asyncio.sleep(1)  # 睡眠一秒钟
+    ```
+    """, strip_indent=4)
+    await actions('点击开始示例', ['开始示例'])
+    set_anchor('counter')
+    for i in range(15, -1, -1):
+        clear_after('counter')
+        text_print('倒计时:%s' % i)
+        await asyncio.sleep(1)  # 睡眠一秒钟
+
+    put_markdown("""#### 环境设置
+    ##### 输出区外观
+    PyWebIO支持两种外观：输出区固定高度/可变高度。
+    可以通过调用`set_output_fixed_height(True)`来开启输出区固定高度。\n
+    你现在看到的是输出区可变高度的形态，你可以点击下面的按钮来切换外观。
+    """, strip_indent=4)
+    buttons([
+        {'label': '输出区固定高度', 'value': 'fixed'},
+        {'label': '输出区可变高度', 'value': 'no-fix'}
+    ], lambda i, _: set_output_fixed_height(i == 'fixed'), small=True)
+
+    put_markdown("""不过你最好在程序一开始就设置好输出区外观，否则你可能就会像现在这样手足无措～
+
+    调用`set_title(title)`可以设置标题，不过标题只能在输出区固定高度时看到。\n
+    """, strip_indent=4)
+
+    async def set_title_btn(data, save):
+        title = await input("Input title")
+        set_title(title)
+
+    buttons(['设置标题'], onclick=set_title_btn)
+
+    await actions('', ['继续教程'])
+
+    put_markdown("""##### 自动滚动
+    通过调用`set_auto_scroll_bottom(True)`来开启自动滚动，当有新内容输出时会自动将页面滚动到底部。\n
+    """, strip_indent=4)
+    buttons([
+        {'label': '开启自动滚动', 'value': 'enable'},
+        {'label': '关闭自动滚动', 'value': 'disable'}
+    ], lambda i, _: set_auto_scroll_bottom(i == 'enable'), small=True)
+
+    put_markdown("""#### Async
+    由于PyWebIO是基于Tornado构建的，而Tornado又与Python标准库<a href="https://docs.python.org/3/library/asyncio.html" target="_blank">asyncio</a>兼容，所以在PyWebIO中，你也可以运行`asyncio`中的协程函数
+
+    这一点其实在上文已经出现过了，不记得了？
+    """, strip_indent=4)
+    buttons(['点此穿越🚀'], onclick=lambda a, b: scroll_to('anchor'))
+
+    #
+    put_markdown("""
+    上文中的例子，之所以要使用asyncio中的sleep函数而不是Python `time`标准库中的sleep函数，是因为Tornado以及`asyncio`实际上是一个单线程模型，当前协程当进行一些需要等待的操作时，可以使用`await`让出程序控制权，框架会选择协程授予执行控制权，而调用`time.sleep`并不会让出程序控制权，因此在程序等待的间隔内，其他协程无法得到执行。更具体的关于协程以及asyncio的讨论已经超出了PyWebIO的范畴，你可以取互联网搜索相关内容来进行了解。
+
+    回到PyWebIO，你也可以`await`自己编写的协程函数
+    ```python
+    import asyncio
+
+    async def request():
+        http_client = AsyncHTTPClient()
+        response = await http_client.fetch("http://example.com")
+        text_print(response.body)
+        return response
+
+    response = await request()
+    ```
+
+    PyWebIO还允许你在一个协程函数中在后台启动另一个协程函数，不会像使用`await`一样阻塞当前协程，当前协程可以继续往下执行。
+
+    ```python
+    import asyncio
+    from datetime import datetime
+
+    async def show_time():
+        for _ in range(10):
+            text_print('现在时间:%s' % datetime.now())
+            await asyncio.sleep(1)
+
+    run_async(show_time())
+    ```
+
+    在新生成的协程内，依然可以调用输入函数，若用户当前已经有正在展示的输入表单，则会被新生成的表单替换，但是旧表单不会被销毁，旧表单的输入状态也会保留，当新表单提交后，旧输入表单会重新呈现给用户。
+    """, strip_indent=4)
+
+    async def show_time():
+        for _ in range(10):
+            text_print('现在时间:%s' % datetime.now())
+            await asyncio.sleep(1)
+
+    buttons(['运行run_async(show_time())'], onclick=lambda a, b: run_async(show_time()))
+    await asyncio.sleep(2)
+
+    await input("当当当当，看，在show_time协程运行的时候，你依然可以进行获取输入", placeholder='随便输入点啥')
+
+    put_markdown("""
+    <hr/>
+
+    以上大概就是 PyWebIO 的所有特性了，如果觉得还不错的话，可以 Give me a 🌟 in <a href="https://github.com/wang0618/PyWebIO" target="_blank">Github</a>
+
+    PS： <a href="https://github.com/wang0618/PyWebIO/blob/master/pywebio/demos/overriew-zh.py" target="_blank">在这里</a>你可以找到生成本页面的脚本
+    PPS：开头提到的彩蛋揭晓："用自己来介绍自己"很具计算机领域风格，对此发挥至极的是<a href="https://en.wikipedia.org/wiki/Quine_(computing)" target="_blank">Quine</a>的概念，"A quine is a program which prints a copy of its own as the only output. "
+    """, strip_indent=4)
+
+
+start_ioloop(feature_overview, debug=True)