中文 | EN
MIAO ( ”Miao Is A web demO generator”的缩写,读音为/mjɑʊ/) 是一个非侵入式的网页演示生成器,能够快捷地将某个函数或者某段代码转化为网页界面,用以临时的演示或者测试,开箱即用而无需复杂的配置过程。
MIAO 并不是一个 Web 框架,其关注点与Web框架有着很大差异,MIAO 主要是用于制作一些临时性的小 Demo 或者小的在线工具,而不是被应用在生产环境中,也不建议被用于正式的项目中。
MIAO 在灵活性与易用性之间作了取舍,主要着眼于提供便捷的,开箱即用的临时网页小 Demo 生成功能,而不提供过多的配置与自定义界面/交互的功能,也不像Web框架那样,提供诸如「权限控制」、「路由」、「模板渲染」、「Session」等功能。
只需三步即可快速创建一个临时小 Demo:
引入库->加装饰器->启动服务
MIAO目前仅支持 Java 和 Python,后续会加入对其他语言(如Golang,JavaScript,Haskell)的支持,敬请期待。
本工具尚未全部开发完成,目前仅能使用部分主要功能,其余功能的实现计划详见后文「规划路线图」章节
(Java 版见:https://github.com/TheColdVoid/MIAO-java )
MIAO 仅支持在 Python3.6 及以上的版本中运行
利用pip来安装MIAO:
pip install miaolib
引入库
from miaolib import web_demo, start
然后只需在想要生成界面的函数,加上 @web_demo() 装饰器,
@web_demo()
def random_num(min:int,max:int):
import random
return random.randint(min,max)
最后在代码文件末尾(或者其他您想要启动服务的地方),启动本工具的服务器端即可
start()
( start() 函数将在执行时阻塞,因此您需将此行代码放在您的其他代码的后面,或者开一个新的线程供本工具提供服务。)
就可以自动生成这样的临时 Demo:
输入参数后,点击「执行」即可执行,并获得返回值:
为了 MIAO 限制可传入的参数类型并完成参数的类型转换,建议您利用 Python 的 Type Hint (PEP 484)对返回值进行类型标注,对于有标注类型参数,MIAO 将会将参数转换成对应的类型,如上例中所示的def random_num(min:int,max:int):
那样。
执行结果可以以「表格」的形式进行可视化(后续会增加其他的可视化形式选项,如「图表」「图片」「树」等)。
如您希望采用执行结果可以以「表格」的形式进行可视化,需将@web_demo装饰器的visualization参数修改为’table’:
@web_demo(visualization='table')
作为简单使用,您可以直接返回由dict组成的list,dict中的每个键将会被作为表格的列,list中每个dict将会作为表格的行,dict中的值即为这行这列的值。 如:
@web_demo(visualization='table')
def interest():
return [
{
'name': "小猫猫",
'coding': True,
'eat': True,
'sleep': False,
'drawing': True,
},
{
'name': "空猫猫",
'coding': True,
'eat': True,
'sleep': True,
'drawing': False,
},
{
'name': "花猫猫",
'coding': True,
'eat': False,
'sleep': True,
'drawing': False,
},
]
即可生成如下的可视化结果:
或者,您也可以新建一个用于存放结果的类:
class Cat():
def __init__(self, name, color, age, length):
self.name = name
self.age = age
self.color = color
self.length = length
然后返回这个类的对象所组成的 List 即可。
from typing import List
@web_demo(visualization='table')
def cat_info() -> List[Cat]:
c1 = Cat("花花", '花', 8, 46)
c2 = Cat("空空", '空', 17, 184)
c3 = Cat("黑黑", '黑', 7, 73)
return [c1, c2, c3]
运行后将会得到如下的可视化结果:
(如果您希望返回对象所组成的 List 的话,您需要利用类型标注(Type Hint)来指明函数的返回值类型,以供 MIAO 识别并展示表头。如上例中函数返回值类型标注-> List[Cat]
)
您如果只是想简单地将一个列表作为返回结果,MIAO 也是支持的。 例如:
@web_demo(visualization='table')
def voice():
return ["喵", "汪", "嗷"]
可以生成如下的结果:
为了 MIAO 能够在您的函数返回空结果时仍能正确显示表头,建议您利用类型标注(Type Hint)对返回值类型进行标注,如:
from typing import List
@web_demo(visualization='table')
def voice() -> List[str]:
return ["喵", "汪", "嗷"]
对于 Python3.8 及以上的版本,您可以利用 typing.TypedDict 来为 dict 类型的返回值标注其所含有的键,如:
from typing import TypedDict, List
class InterestTable(TypedDict):
name: str
coding: bool
eat: bool
sleep: bool
drawing: bool
@web_demo(visualization='table')
def interest() -> List[InterestTable]:
# return some cat's interest dict here
这样当返回空表时,表头也将会被正确地显示:
您也可以选择手动指定表头中的列名:
@web_demo(visualization='table',table_headers=["name","coding","eat"])
def interest() :
# return some cat's interest dict here
这个功能也一样可以被用来限制或筛选表格中要被显示的列:
当然,本工具也提供了一些简单的定制化选项,例如您可以修改函数名、函数简介、参数名等:
@web_demo('两数相加', description="返回两个数相加的结果",param_names=['操作数1','操作数2'])
def func1(a: int, b: int):
return a + b
上方的标题也可以通过参数来进行修改:Cat Ear Switch Controller
start("Cat Ear Switch Controller")
将来会增加更多的定制项(例如参数的选择方式、配色等等)
PS:由于本工具尚未全部开发完成,现在暂时函数参数和返回值只支持基本数据类型,可视化形式只支持「表格」,后续将会加入对「图片」「图表」「复杂对象」「文件」「视频」「函数图像」等的支持,详见「规划路线图」章节
MIAO 是”Miao Is A web demO generator”的缩写,同时也是汉语中用来形容猫叫声的音节(喵,读作miāo),类似「meow」和「にゃ」(≧∇≦)。
平时提到这个工具的名字的时候,也可以称之为 MiaoLib,以避免产生歧义或者和猫叫声混淆。
MIAO 并不是一个Web框架,其关注点与Web框架有着很大差异,两者之间更多的是互补的关系。MIAO 主要关注的是如下场景下的应用:
示例的代码请点击链接查看。
示例演示了一些可能的使用场景,
如果您有更好的使用示例,欢迎提 PR 或直接联系我,我将会将其加入本章节,谢谢。
以下功能将逐步被加进本工具中。如果您对本项目有兴趣,也欢迎您通过fork和PR来为本项目贡献代码。
在设计框架的功能的时候,比起灵活性和可定制性,本框架更注重易用性,并追求零配置和开箱即用的特性,本框架主要应对的是需要生成临时 Demo 和简易的界面的场景,所以本框架中将不会增加修改界面结构或者样式的 API。如果有复杂的界面需求,Web 框架或许是更好的选择。
当然,不排除后续我们增加一些简易的界面主题设置项,用以更换界面的风格或者配色,但是不会提供「修改界面端的网页结构、布局 CSS 样式」这种复杂的定制 API。
不过,界面代码也是开源的,也欢迎您直接 fork 界面的代码(这里贴代码仓库地址)来直接进行修改,后续我们会加入更改界面网页(前端)的API。
如果您对本项目有兴趣,也欢迎您通过 fork 和 PR 来为本项目贡献代码喵。
如果代码运行中遇到了什么问题,或者您发现了 Bug,也欢迎您通过 Issue 或者直接联系我来进行反馈,我会尽快给予答复喵。
联系方式:
thevoid2333@gmail.com
或者直接提 Issue 喵~