excel-vis 0.1.0__tar.gz

excel_vis-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chandler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

excel_vis-0.1.0/PKG-INFO

@@ -0,0 +1,485 @@
+Metadata-Version: 2.4
+Name: excel-vis
+Version: 0.1.0
+Summary: A lightweight web application for Excel data management and visualization, powered by FastAPI + Tailwind CSS + Alpine.js
+Author-email: Chandler <275737875@qq.com>
+License-Expression: MIT
+Keywords: excel,fastapi,web,visualization,data-management
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn[standard]>=0.20.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: python-multipart>=0.0.6
+Requires-Dist: jinja2>=3.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: httpx>=0.24.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Dynamic: license-file
+
+# Excel-Vis
+
+**一个让你用浏览器轻松管理 Excel 数据的工具。**
+
+Excel-Vis 是一个基于 Python 的轻量级 Web 应用，它把你电脑上的 Excel 文件变成一个可以在浏览器中查看、编辑、新增、删除数据的网页系统。你不需要安装任何数据库，Excel 文件本身就是你的"数据库"。
+
+简单来说：**安装 → 一行命令启动 → 打开浏览器就能管理你的 Excel 数据。**
+
+---
+
+## 功能特性
+
+- **浏览器查看 Excel 数据**：以美观的网页表格展示 Excel 文件内容，支持手机访问
+- **在线增删改查**：直接在网页上新增、编辑、删除记录，修改会自动保存到 Excel 文件
+- **单击查看详情**：点击任意一行，弹窗展示该行所有字段的完整信息
+- **Excel 导入/导出**：支持上传 Excel 文件导入数据（追加或覆盖），也可导出当前数据
+- **支持任意结构**：不限定 Excel 的列名和列数，系统自动识别表头
+- **自定义列显示**：可以选择显示哪些列、修改列的显示名称、拖拽调整列顺序
+- **布局设置**：支持紧凑/标准/宽松三种表格密度，可设置每页显示行数
+- **双渠道编辑**：网页端修改自动写入 Excel；你也可以直接编辑 Excel 文件，刷新网页即可看到最新内容
+- **一键启动**：安装后一条命令即可运行，自动打开浏览器
+- **零配置**：无需数据库，无需复杂配置，开箱即用
+
+---
+
+## 安装指南
+
+### 环境要求
+
+- **Python 版本**：3.9 或更高版本
+- **操作系统**：Windows、macOS、Linux 均可
+- **浏览器**：Chrome、Firefox、Edge、Safari 等现代浏览器
+
+### 第一步：检查 Python 版本
+
+打开你的终端（Windows 用户打开"命令提示符"或"PowerShell"），输入：
+
+```bash
+python --version
+```
+
+如果显示 `Python 3.9.x` 或更高版本，说明环境已就绪。如果版本过低或未安装，请前往 [python.org](https://www.python.org/downloads/) 下载安装。
+
+### 第二步：安装 excel-vis
+
+```bash
+pip install excel-vis
+```
+
+等待安装完成即可。这会自动安装所有需要的依赖包。
+
+### 第三步：验证安装
+
+```bash
+excel-vis --help
+```
+
+如果看到帮助信息输出，说明安装成功。
+
+---
+
+## 使用教程
+
+### 快速启动（最简单的方式）
+
+在终端中进入你想存放 Excel 文件的目录，然后运行：
+
+```bash
+excel-vis
+```
+
+系统会自动：
+1. 在当前目录创建一个带有示例数据的 `data.xlsx` 文件（如果不存在的话）
+2. 启动 Web 服务
+3. 自动打开浏览器展示数据
+
+### 指定已有的 Excel 文件
+
+如果你已经有一个 Excel 文件，可以直接指定它：
+
+```bash
+excel-vis --file /path/to/your/file.xlsx
+```
+
+**Windows 示例：**
+```bash
+excel-vis --file C:\Users\张三\Documents\员工信息.xlsx
+```
+
+**macOS/Linux 示例：**
+```bash
+excel-vis --file ~/Documents/员工信息.xlsx
+```
+
+### 更多启动参数
+
+```bash
+# 指定端口号（默认 8000）
+excel-vis --port 8080
+
+# 指定监听地址（让局域网内其他电脑也能访问）
+excel-vis --host 0.0.0.0 --port 8080
+
+# 不自动打开浏览器
+excel-vis --no-browser
+
+# 完整示例：指定文件、端口、不打开浏览器
+excel-vis --file mydata.xlsx --port 9000 --no-browser
+```
+
+### 在 Python 代码中使用
+
+如果你是开发者，也可以在 Python 代码中直接调用：
+
+```python
+import excel_vis
+
+# 最简单的方式：一行代码启动
+excel_vis.run()
+
+# 自定义参数启动
+excel_vis.run(
+    file="mydata.xlsx",   # Excel 文件路径
+    host="0.0.0.0",       # 监听地址
+    port=8080,            # 端口号
+    open_browser=True     # 是否自动打开浏览器
+)
+
+# 只创建 FastAPI 应用实例（用于集成到自己的项目中）
+app = excel_vis.create_app(file="mydata.xlsx")
+```
+
+### 通过模块方式运行
+
+```bash
+python -m excel_vis --file data.xlsx --port 8000
+```
+
+---
+
+## 网页操作指南
+
+启动后打开浏览器，你会看到一个数据管理界面。以下是各功能的使用方法：
+
+### 查看数据
+
+- 页面加载后自动显示 Excel 中的所有数据
+- 表格支持分页浏览，底部可切换页码
+- 在手机上访问时，表格可左右滑动
+
+### 查看某行详情
+
+- **单击表格中的任意一行**，会弹出一个窗口，展示该行所有字段的名称和值
+- 在详情窗口中可以直接点击"编辑"进入编辑模式
+
+### 新增记录
+
+1. 点击顶部工具栏的 **"新增"** 按钮
+2. 在弹出的表单中填写各字段（ID 会自动生成，不需要手动填）
+3. 点击 **"保存"**，数据将写入 Excel 文件并刷新表格
+
+### 编辑记录
+
+1. 点击某行右侧的 **编辑图标**（笔形图标）
+2. 修改需要更改的字段
+3. 点击 **"保存"**，修改将同步到 Excel 文件
+
+### 删除记录
+
+1. 点击某行右侧的 **删除图标**（垃圾桶图标）
+2. 系统会弹出确认对话框，防止误操作
+3. 确认后该行将从 Excel 文件中永久删除
+
+### 导入 Excel 文件
+
+1. 点击顶部工具栏的 **"导入"** 按钮
+2. 选择一个 `.xlsx` 或 `.xls` 文件
+3. 选择导入模式：
+   - **追加模式**：保留原有数据，把新文件中的数据添加到末尾
+   - **覆盖模式**：删除所有原有数据，完全用新文件替换
+4. 点击 **"开始导入"**
+
+### 导出 Excel 文件
+
+- 点击顶部工具栏的 **"导出"** 按钮
+- 浏览器会自动下载一个 Excel 文件，文件名格式为 `数据导出_日期_时间.xlsx`
+
+### 刷新数据
+
+- 如果你在外部直接编辑了 Excel 文件，点击 **"刷新"** 按钮即可加载最新数据
+
+### 自定义列设置
+
+1. 点击顶部工具栏的 **"列设置"** 按钮
+2. 在右侧弹出的面板中可以：
+   - **勾选/取消勾选**：控制哪些列在表格中显示
+   - **修改显示名称**：把英文列名改成中文等自定义名称
+   - **拖拽排序**：按住左侧拖拽图标调整列的显示顺序
+   - **切换表格密度**：紧凑/标准/宽松
+   - **设置每页行数**：10/20/50/100
+3. 点击 **"应用"** 保存设置
+4. 这些设置保存在浏览器中，下次打开页面会自动恢复
+
+---
+
+## API 接口说明
+
+Excel-Vis 提供标准的 RESTful API，可以被其他程序调用。启动服务后，API 基础地址为 `http://localhost:8000`（端口号取决于你的设置）。
+
+### 获取所有数据
+
+```
+GET /api/data
+```
+
+**响应示例：**
+```json
+{
+  "code": 200,
+  "data": [
+    {"id": 1, "姓名": "张三", "年龄": 28, "邮箱": "zh@ex.com", "部门": "技术部"},
+    {"id": 2, "姓名": "李芳", "年龄": 32, "邮箱": "li@ex.com", "部门": "市场部"}
+  ]
+}
+```
+
+### 获取单条记录
+
+```
+GET /api/data/{id}
+```
+
+**示例：** `GET /api/data/1`
+
+**响应：**
+```json
+{
+  "code": 200,
+  "data": {"id": 1, "姓名": "张三", "年龄": 28, "邮箱": "zh@ex.com", "部门": "技术部"}
+}
+```
+
+### 新增记录
+
+```
+POST /api/data
+Content-Type: application/json
+
+{"姓名": "王五", "年龄": 25, "邮箱": "wang@ex.com", "部门": "产品部"}
+```
+
+**响应：**
+```json
+{"code": 200, "message": "ok", "id": 3}
+```
+
+### 更新记录
+
+```
+PUT /api/data/{id}
+Content-Type: application/json
+
+{"姓名": "王五改", "年龄": 26}
+```
+
+**响应：**
+```json
+{"code": 200, "message": "ok"}
+```
+
+### 删除记录
+
+```
+DELETE /api/data/{id}
+```
+
+**响应：**
+```json
+{"code": 200, "message": "ok"}
+```
+
+### 获取列信息
+
+```
+GET /api/columns
+```
+
+**响应：**
+```json
+{"code": 200, "columns": ["id", "姓名", "年龄", "邮箱", "部门", "入职日期"]}
+```
+
+### 导入 Excel
+
+```
+POST /api/import
+Content-Type: multipart/form-data
+
+file: <Excel 文件>
+mode: append 或 overwrite
+```
+
+**响应：**
+```json
+{"code": 200, "message": "追加导入成功，共导入 5 条记录"}
+```
+
+### 导出 Excel
+
+```
+GET /api/export
+```
+
+返回 `.xlsx` 文件下载。
+
+---
+
+## 依赖项清单
+
+| 依赖包 | 最低版本 | 用途 |
+|--------|---------|------|
+| fastapi | 0.100.0 | Web 框架，提供 API 服务 |
+| uvicorn[standard] | 0.20.0 | ASGI 服务器，运行 FastAPI 应用 |
+| openpyxl | 3.1.0 | 读写 Excel (.xlsx) 文件 |
+| typer | 0.9.0 | 命令行界面（CLI）框架 |
+| python-multipart | 0.0.6 | 处理文件上传 |
+| jinja2 | 3.1.0 | HTML 模板渲染 |
+
+**开发依赖（可选）：**
+
+| 依赖包 | 用途 |
+|--------|------|
+| pytest | 运行测试 |
+| httpx | API 测试客户端 |
+| pytest-asyncio | 异步测试支持 |
+
+---
+
+## 常见问题
+
+### Q: 启动后浏览器没有自动打开怎么办？
+
+手动打开浏览器，访问终端中显示的地址（默认为 `http://127.0.0.1:8000`）。
+
+### Q: 提示端口被占用怎么办？
+
+换一个端口号启动：
+
+```bash
+excel-vis --port 9000
+```
+
+### Q: 我的 Excel 文件没有 id 列怎么办？
+
+没有关系！系统会自动添加 `id` 列并为每行生成唯一编号，不会影响你原有的数据。
+
+### Q: 我直接用 Excel 软件修改了文件，网页上怎么看到新数据？
+
+点击网页上的 **"刷新"** 按钮，即可重新加载 Excel 文件中的最新内容。
+
+### Q: 可以多人同时使用吗？
+
+本工具设计为**单用户或小团队轻量使用**。由于 Excel 文件不支持并发写入，建议同一时间只有一个人进行编辑操作。多人同时查看数据是没有问题的。
+
+### Q: 支持哪些格式的 Excel 文件？
+
+支持 `.xlsx`（推荐）和 `.xls` 格式。导出时统一使用 `.xlsx` 格式。
+
+### Q: 数据量有限制吗？
+
+建议 Excel 文件不超过 **10,000 行 × 30 列**。超过此规模可能会导致加载变慢。
+
+### Q: 如何让局域网内其他电脑访问？
+
+启动时指定 host 为 `0.0.0.0`：
+
+```bash
+excel-vis --host 0.0.0.0 --port 8000
+```
+
+然后其他电脑在浏览器中输入 `http://你的IP地址:8000` 即可访问。
+
+### Q: 上传文件有大小限制吗？
+
+默认限制为 **10MB**。如果需要导入更大的文件，建议先精简数据或分批导入。
+
+---
+
+## 免责声明
+
+### 使用风险
+
+1. **数据安全**：本软件直接读写 Excel 文件，操作不可撤销。删除或覆盖导入等操作会**永久修改**你的 Excel 文件。强烈建议在使用前**备份重要数据**。
+
+2. **非生产环境工具**：本软件为轻量级数据管理工具，适用于个人使用、小团队内部管理、数据演示等场景。**不建议**用于生产环境、金融交易、医疗记录等对数据安全性和可靠性有严格要求的场景。
+
+3. **并发限制**：本软件使用 Excel 文件作为数据存储，不具备数据库级别的并发控制能力。多人同时写入可能导致数据冲突或丢失。
+
+4. **网络安全**：本软件默认不包含用户认证和权限控制。如果部署在公网环境中，任何能够访问该地址的人都可以查看和修改你的数据。请勿在不受信任的网络环境中使用，或自行配置防火墙和访问控制。
+
+5. **文件完整性**：如果 Excel 文件在使用过程中被外部程序（如 Excel 软件）同时打开并编辑，可能导致文件损坏或数据不一致。
+
+### 责任归属
+
+- 本软件按"现状"提供，作者**不对因使用本软件而导致的任何数据丢失、损坏、泄露或其他损失承担责任**。
+- 用户应自行评估使用本软件的风险，并采取必要的数据备份和安全防护措施。
+- 用户应确保其使用本软件的方式符合所在地区的法律法规。
+
+### 使用建议
+
+- 使用前务必**备份** Excel 文件
+- 定期通过"导出"功能下载数据备份
+- 避免在公网环境中不加防护地部署
+- 避免多人同时进行写入操作
+- 重要数据请使用专业数据库系统管理
+
+---
+
+## 贡献指南
+
+欢迎贡献代码、报告问题或提出建议！
+
+1. Fork 本项目
+2. 创建你的功能分支：`git checkout -b feature/my-feature`
+3. 提交更改：`git commit -m "Add my feature"`
+4. 推送到分支：`git push origin feature/my-feature`
+5. 创建 Pull Request
+
+### 开发环境搭建
+
+```bash
+# 克隆项目
+git clone https://github.com/your-repo/excel-vis.git
+cd excel-vis
+
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 运行测试
+pytest tests/ -v
+```
+
+---
+
+## 许可证信息
+
+本项目采用 **MIT 许可证** 开源。
+
+你可以自由地使用、复制、修改、合并、发布、分发本软件，但需要在软件的所有副本中包含版权声明和许可证声明。
+
+详见 [LICENSE](./LICENSE) 文件。
+
+
+