magic-dash

面向 Dash 应用开发的命令行脚手架，快速生成可运行、可扩展的 Python 数据应用模板。

magic-dash 内置单页面工具、多页面应用和带登录鉴权的管理系统模板，覆盖路由、菜单、配置、回调组织、状态页、数据库模型、用户与权限管理等常见工程起点。

快速开始

安装 magic-dash：

pip install magic-dash -U

查看当前可生成的模板：

magic-dash list

交互式创建项目：

magic-dash create

指定模板创建项目：

magic-dash create --name magic-dash

指定生成目录：

magic-dash create --name magic-dash --path ./workspace

生成项目后，进入项目目录安装模板依赖并启动：

cd 生成的项目目录
pip install -r requirements.txt
python app.py

magic-dash-pro 模板需要先初始化数据库和登录密钥：

cd 生成的项目目录
pip install -r requirements.txt
python -m models.init_db
python app.py

默认访问地址：

http://127.0.0.1:8050

magic-dash-pro 初始化后的默认管理员账号：

用户名：admin
密码：admin123

完整命令说明见 magic-dash 命令使用。

内置模板

模板	定位	典型场景	详细文档
simple-tool	单页面工具应用模板	内部小工具、数据处理表单、快速验证页面	查看
magic-dash	基础多页面应用模板	多页面后台雏形、数据看板、路由演示项目	查看
magic-dash-pro	多页面加登录鉴权管理系统模板	用户体系、角色权限、数据库管理后台	查看

magic-dash-pro 会在生成时选择后端类型：

• magic-dash-pro Flask 后端说明：默认后端，基于 flask-login 和 flask-principal。
• magic-dash-pro FastAPI 后端说明：基于 Dash 的 backend="fastapi" 能力和 fastapi-login。

文档导航

• magic-dash 命令使用
• simple-tool 模板介绍
• magic-dash 模板介绍
• magic-dash-pro 模板介绍
• magic-dash-pro Flask 后端模板
• magic-dash-pro FastAPI 后端模板
• 配置参数说明
• 二次开发介绍

生成项目结构概览

simple-tool 生成最小单文件结构：

simple-tool/
├─ app.py
└─ requirements.txt

magic-dash 生成标准多页面结构：

magic-dash/
├─ assets/
├─ callbacks/
├─ components/
├─ configs/
├─ utils/
├─ views/
├─ server.py
├─ app.py
└─ requirements.txt

magic-dash-pro 在多页面结构基础上增加鉴权和数据模型：

magic-dash-pro/
├─ assets/
├─ callbacks/
├─ components/
├─ configs/
├─ models/
├─ utils/
├─ views/
├─ server.py
├─ app.py
└─ requirements.txt

目录职责、页面扩展和回调组织方式见 二次开发介绍。

配置能力

生成后的 magic-dash 系列模板通过 configs/ 目录集中维护配置：

• BaseConfig：应用标题、版本号、浏览器版本限制、更新日志弹窗、登录安全相关配置。
• LayoutConfig：侧边栏宽度、核心页面呈现类型、页面搜索、登录页左侧内容类型。
• RouterConfig：首页别名、侧边菜单、有效页面、独立页面、通配页面、公开页面。
• AuthConfig：magic-dash-pro 的角色定义与页面访问规则。
• DatabaseConfig：magic-dash-pro 的 SQLite、PostgreSQL、MySQL 数据库连接配置。

完整参数表见 配置参数说明。

技术栈

magic-dash 命令行工具本身使用：

• click：命令行接口。
• questionary：交互式选择与确认。
• rich：终端输出美化。
• setuptools：项目打包。

生成后的应用模板使用：

• Dash：应用框架。
• feffery-antd-components：基于 Ant Design 风格的 Dash 组件。
• feffery-utils-components：浏览器侧实用组件。
• feffery-dash-utils：版本检查、样式工具等辅助能力。
• feffery-markdown-components：Markdown 渲染组件。
• peewee：magic-dash-pro 数据库模型层。
• cryptography：magic-dash-pro 登录密码加密传输相关能力。

本地开发与测试

克隆仓库后，可以用可编辑模式安装：

pip install -e .

运行测试：

pytest

当前测试重点覆盖 magic-dash 命令行入口、模板列表、模板生成、magic-dash-pro 后端选择和非法模板错误处理。更多开发约定见 二次开发介绍。

许可证

本项目基于 MIT License 开源。

更多教程

微信公众号「玩转 Dash」

「玩转 Dash」知识星球