excel-vis 0.1.0__py3-none-any.whl

excel_vis/__init__.py

@@ -0,0 +1,62 @@
+"""excel-vis: A lightweight web application for Excel data management.
+
+Usage:
+    # CLI
+    excel-vis --file data.xlsx --port 8000
+
+    # Python API
+    import excel_vis
+    excel_vis.run(file="data.xlsx", port=8000)
+"""
+
+__version__ = "0.1.0"
+
+
+def create_app(file: str = "data.xlsx"):
+    """Create a FastAPI application instance.
+
+    Args:
+        file: Path to the Excel file to use as data source.
+
+    Returns:
+        Configured FastAPI application.
+    """
+    from excel_vis.app import create_app as _create_app
+
+    return _create_app(file=file)
+
+
+def run(
+    file: str = "data.xlsx",
+    host: str = "0.0.0.0",
+    port: int = 8000,
+    open_browser: bool = True,
+):
+    """Start the excel-vis Web service.
+
+    Args:
+        file: Path to the Excel file to use as data source.
+        host: Host address to bind to.
+        port: Port number to listen on.
+        open_browser: Whether to automatically open a browser window.
+    """
+    import webbrowser
+    from threading import Timer
+
+    import uvicorn
+
+    from excel_vis.app import create_app as _create_app
+    from excel_vis.config import update_settings
+
+    update_settings(file_path=file, host=host, port=port, open_browser=open_browser)
+
+    if open_browser:
+
+        def _open():
+            browse_host = "127.0.0.1" if host == "0.0.0.0" else host
+            webbrowser.open(f"http://{browse_host}:{port}")
+
+        Timer(1.5, _open).start()
+
+    application = _create_app(file=file)
+    uvicorn.run(application, host=host, port=port, log_level="info")

excel_vis/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running excel-vis as a module: python -m excel_vis"""
+
+from excel_vis.cli import app
+
+if __name__ == "__main__":
+    app()

excel_vis/api/__init__.py

@@ -0,0 +1 @@
+"""API package."""

excel_vis/api/columns.py

@@ -0,0 +1,17 @@
+"""Columns API route."""
+
+from fastapi import APIRouter, HTTPException
+
+from excel_vis.services import excel_service
+
+router = APIRouter(prefix="/api")
+
+
+@router.get("/columns")
+async def get_columns():
+    """Get column names from the Excel file."""
+    try:
+        columns = excel_service.get_columns()
+        return {"code": 200, "columns": columns}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"获取列信息失败: {str(e)}")

excel_vis/api/data.py

@@ -0,0 +1,73 @@
+"""CRUD API routes for data records."""
+
+from fastapi import APIRouter, HTTPException, Request
+
+from excel_vis.services import excel_service
+
+router = APIRouter(prefix="/api")
+
+
+@router.get("/data")
+async def get_all_data():
+    """Get all records."""
+    try:
+        data = excel_service.read_all()
+        return {"code": 200, "data": data}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"读取数据失败: {str(e)}")
+
+
+@router.get("/data/{record_id}")
+async def get_one_data(record_id: int):
+    """Get a single record by ID."""
+    try:
+        record = excel_service.read_one(record_id)
+        if record is None:
+            raise HTTPException(status_code=404, detail=f"记录 ID={record_id} 不存在")
+        return {"code": 200, "data": record}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"读取数据失败: {str(e)}")
+
+
+@router.post("/data")
+async def create_data(request: Request):
+    """Create a new record."""
+    try:
+        body = await request.json()
+        # Remove id if provided, backend will auto-generate
+        body.pop("id", None)
+        new_id = await excel_service.create(body)
+        return {"code": 200, "message": "ok", "id": new_id}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"新增记录失败: {str(e)}")
+
+
+@router.put("/data/{record_id}")
+async def update_data(record_id: int, request: Request):
+    """Update an existing record."""
+    try:
+        body = await request.json()
+        success = await excel_service.update(record_id, body)
+        if not success:
+            raise HTTPException(status_code=404, detail=f"记录 ID={record_id} 不存在")
+        return {"code": 200, "message": "ok"}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"更新记录失败: {str(e)}")
+
+
+@router.delete("/data/{record_id}")
+async def delete_data(record_id: int):
+    """Delete a record by ID."""
+    try:
+        success = await excel_service.delete(record_id)
+        if not success:
+            raise HTTPException(status_code=404, detail=f"记录 ID={record_id} 不存在")
+        return {"code": 200, "message": "ok"}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"删除记录失败: {str(e)}")

excel_vis/api/file_ops.py

@@ -0,0 +1,69 @@
+"""File operations API routes (import/export)."""
+
+from datetime import datetime
+from urllib.parse import quote
+
+from fastapi import APIRouter, File, Form, HTTPException, UploadFile
+from fastapi.responses import Response
+
+from excel_vis.config import get_settings
+from excel_vis.services import excel_service
+
+router = APIRouter(prefix="/api")
+
+ALLOWED_EXTENSIONS = {".xlsx", ".xls"}
+
+
+def _validate_file(filename: str) -> None:
+    """Validate uploaded file extension."""
+    if not filename:
+        raise HTTPException(status_code=400, detail="未提供文件名")
+    ext = "." + filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
+    if ext not in ALLOWED_EXTENSIONS:
+        raise HTTPException(
+            status_code=400,
+            detail=f"不支持的文件格式: {ext}，仅支持 .xlsx 和 .xls",
+        )
+
+
+@router.post("/import")
+async def import_excel(file: UploadFile = File(...), mode: str = Form("append")):
+    """Import Excel file (append or overwrite mode)."""
+    _validate_file(file.filename)
+
+    if mode not in ("append", "overwrite"):
+        raise HTTPException(status_code=400, detail="mode 参数必须为 'append' 或 'overwrite'")
+
+    # Check file size
+    content = await file.read()
+    max_size = get_settings().max_upload_size
+    if len(content) > max_size:
+        raise HTTPException(
+            status_code=400,
+            detail=f"文件大小超过限制 ({max_size // 1024 // 1024}MB)",
+        )
+
+    try:
+        message = await excel_service.import_data(content, mode)
+        return {"code": 200, "message": message}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"导入失败: {str(e)}")
+
+
+@router.get("/export")
+async def export_excel():
+    """Export current data as an Excel file download."""
+    try:
+        content = excel_service.export_data()
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        filename = f"数据导出_{timestamp}.xlsx"
+        encoded_filename = quote(filename)
+        return Response(
+            content=content,
+            media_type="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+            headers={"Content-Disposition": f"attachment; filename*=UTF-8''{encoded_filename}"},
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"导出失败: {str(e)}")

excel_vis/app.py

@@ -0,0 +1,54 @@
+"""FastAPI application factory."""
+
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+from jinja2 import Environment, FileSystemLoader
+
+from excel_vis.api import columns, data, file_ops
+from excel_vis.config import get_settings
+
+TEMPLATES_DIR = Path(__file__).parent / "templates"
+STATIC_DIR = Path(__file__).parent / "static"
+
+
+def create_app(file: str = "data.xlsx") -> FastAPI:
+    """Create and configure a FastAPI application instance.
+
+    Args:
+        file: Path to the Excel file to use as data source.
+
+    Returns:
+        Configured FastAPI application.
+    """
+    from excel_vis.config import update_settings
+
+    update_settings(file_path=file)
+
+    app = FastAPI(
+        title="Excel 数据管理系统",
+        description="基于 Excel 的轻量级 Web 数据管理应用",
+        version="0.1.0",
+    )
+
+    # Register API routers
+    app.include_router(data.router)
+    app.include_router(columns.router)
+    app.include_router(file_ops.router)
+
+    # Mount static files if directory exists
+    if STATIC_DIR.exists():
+        app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")
+
+    # Setup Jinja2 template
+    jinja_env = Environment(loader=FileSystemLoader(str(TEMPLATES_DIR)))
+
+    @app.get("/", response_class=HTMLResponse)
+    async def index():
+        """Serve the main HTML page."""
+        template = jinja_env.get_template("index.html")
+        return template.render()
+
+    return app

excel_vis/cli.py

@@ -0,0 +1,48 @@
+"""Typer CLI entry point for excel-vis."""
+
+import webbrowser
+from threading import Timer
+from typing import Optional
+
+import typer
+import uvicorn
+
+app = typer.Typer(
+    name="excel-vis",
+    help="Excel 数据管理与展示系统 - 基于 FastAPI 的轻量级 Web 应用",
+    add_completion=False,
+)
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    file: str = typer.Option("data.xlsx", "--file", "-f", help="Excel 文件路径"),
+    host: str = typer.Option("127.0.0.1", "--host", "-H", help="监听地址"),
+    port: int = typer.Option(8888, "--port", "-p", help="端口号"),
+    no_browser: bool = typer.Option(False, "--no-browser", help="不自动打开浏览器"),
+):
+    """启动 Excel 数据管理 Web 服务。"""
+    from excel_vis.app import create_app
+    from excel_vis.config import update_settings
+
+    update_settings(file_path=file, host=host, port=port, open_browser=not no_browser)
+
+    typer.echo(f"📊 Excel-Vis 启动中...")
+    typer.echo(f"   文件: {file}")
+    typer.echo(f"   地址: http://{host}:{port}")
+
+    if not no_browser:
+
+        def open_browser():
+            browse_host = "127.0.0.1" if host == "0.0.0.0" else host
+            webbrowser.open(f"http://{browse_host}:{port}")
+
+        Timer(1.5, open_browser).start()
+
+    # Create app and run
+    application = create_app(file=file)
+    uvicorn.run(application, host=host, port=port, log_level="info")
+
+
+if __name__ == "__main__":
+    app()

excel_vis/config.py

@@ -0,0 +1,35 @@
+"""Configuration module for excel-vis."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class Settings:
+    """Application settings."""
+
+    file_path: str = "data.xlsx"
+    host: str = "0.0.0.0"
+    port: int = 8000
+    open_browser: bool = True
+    max_upload_size: int = 10 * 1024 * 1024  # 10MB
+
+    @property
+    def excel_path(self) -> Path:
+        return Path(self.file_path).resolve()
+
+
+# Global settings instance
+_settings: Settings = Settings()
+
+
+def get_settings() -> Settings:
+    """Get the current settings instance."""
+    return _settings
+
+
+def update_settings(**kwargs) -> Settings:
+    """Update global settings with provided values."""
+    global _settings
+    _settings = Settings(**kwargs)
+    return _settings

excel_vis/services/__init__.py

@@ -0,0 +1 @@
+"""Services package."""

excel_vis/services/excel_service.py

@@ -0,0 +1,390 @@
+"""Excel service layer for reading and writing Excel files."""
+
+import asyncio
+from datetime import datetime
+from io import BytesIO
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from openpyxl import Workbook, load_workbook
+from openpyxl.utils import get_column_letter
+
+from excel_vis.config import get_settings
+
+# Global lock for file write operations
+_file_lock = asyncio.Lock()
+
+# Default sample data when no file exists
+DEFAULT_COLUMNS = ["id", "姓名", "年龄", "邮箱", "部门", "入职日期"]
+DEFAULT_DATA = [
+    [1, "张三", 28, "zh@ex.com", "技术部", "2023-05-01"],
+    [2, "李芳", 32, "li@ex.com", "市场部", "2023-07-15"],
+]
+
+
+def _get_file_path() -> Path:
+    """Get the configured Excel file path."""
+    return get_settings().excel_path
+
+
+def _ensure_file_exists() -> None:
+    """Ensure the Excel file exists; create with sample data if not."""
+    file_path = _get_file_path()
+    if not file_path.exists():
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        wb = Workbook()
+        ws = wb.active
+        ws.title = "Sheet1"
+        ws.append(DEFAULT_COLUMNS)
+        for row in DEFAULT_DATA:
+            ws.append(row)
+        wb.save(str(file_path))
+
+
+def _load_workbook_safe() -> Tuple[Workbook, Any]:
+    """Load workbook safely, creating it if needed."""
+    _ensure_file_exists()
+    file_path = _get_file_path()
+    try:
+        wb = load_workbook(str(file_path))
+    except Exception:
+        # File is corrupted, recreate it
+        file_path.unlink(missing_ok=True)
+        _ensure_file_exists()
+        wb = load_workbook(str(file_path))
+    ws = wb.active
+    return wb, ws
+
+
+def _get_next_id(ws) -> int:
+    """Get the next auto-increment ID."""
+    headers = [cell.value for cell in ws[1]]
+    if "id" not in headers:
+        return 1
+    id_col_idx = headers.index("id")
+    max_id = 0
+    for row in ws.iter_rows(min_row=2, values_only=True):
+        if row[id_col_idx] is not None:
+            try:
+                val = int(row[id_col_idx])
+                if val > max_id:
+                    max_id = val
+            except (ValueError, TypeError):
+                pass
+    return max_id + 1
+
+
+def _cell_value_to_str(value) -> Any:
+    """Convert cell value to a JSON-serializable format."""
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return value.strftime("%Y-%m-%d")
+    return value
+
+
+def get_columns() -> List[str]:
+    """Get column names from the Excel file."""
+    _ensure_file_exists()
+    wb, ws = _load_workbook_safe()
+    headers = [cell.value for cell in ws[1] if cell.value is not None]
+    wb.close()
+    return headers
+
+
+def read_all() -> List[Dict[str, Any]]:
+    """Read all records from the Excel file."""
+    wb, ws = _load_workbook_safe()
+    headers = [cell.value for cell in ws[1]]
+    # Filter out None headers
+    valid_indices = [i for i, h in enumerate(headers) if h is not None]
+    valid_headers = [headers[i] for i in valid_indices]
+
+    data = []
+    for row in ws.iter_rows(min_row=2, values_only=True):
+        if all(v is None for v in row):
+            continue
+        record = {}
+        for idx in valid_indices:
+            val = row[idx] if idx < len(row) else None
+            record[valid_headers[valid_indices.index(idx)]] = _cell_value_to_str(val)
+        data.append(record)
+    wb.close()
+    return data
+
+
+def read_one(record_id: int) -> Optional[Dict[str, Any]]:
+    """Read a single record by ID."""
+    wb, ws = _load_workbook_safe()
+    headers = [cell.value for cell in ws[1]]
+    if "id" not in headers:
+        wb.close()
+        return None
+
+    id_col_idx = headers.index("id")
+    valid_indices = [i for i, h in enumerate(headers) if h is not None]
+    valid_headers = [headers[i] for i in valid_indices]
+
+    for row in ws.iter_rows(min_row=2, values_only=True):
+        if row[id_col_idx] is not None:
+            try:
+                if int(row[id_col_idx]) == record_id:
+                    record = {}
+                    for idx in valid_indices:
+                        val = row[idx] if idx < len(row) else None
+                        record[valid_headers[valid_indices.index(idx)]] = _cell_value_to_str(val)
+                    wb.close()
+                    return record
+            except (ValueError, TypeError):
+                pass
+    wb.close()
+    return None
+
+
+async def create(data: Dict[str, Any]) -> int:
+    """Create a new record. Returns the new ID."""
+    async with _file_lock:
+        wb, ws = _load_workbook_safe()
+        headers = [cell.value for cell in ws[1]]
+        valid_headers = [h for h in headers if h is not None]
+
+        # Ensure id column exists
+        if "id" not in valid_headers:
+            valid_headers.insert(0, "id")
+            ws.insert_cols(1)
+            ws.cell(row=1, column=1, value="id")
+            headers = ["id"] + headers
+
+        new_id = _get_next_id(ws)
+        data["id"] = new_id
+
+        # Check if new columns need to be added
+        for key in data.keys():
+            if key not in valid_headers:
+                valid_headers.append(key)
+                col_num = len(valid_headers)
+                ws.cell(row=1, column=col_num, value=key)
+
+        # Re-read headers after potential additions
+        headers = [cell.value for cell in ws[1]]
+
+        # Create new row
+        new_row = []
+        for h in headers:
+            if h is not None:
+                new_row.append(data.get(h))
+            else:
+                new_row.append(None)
+        ws.append(new_row)
+        wb.save(str(_get_file_path()))
+        wb.close()
+        return new_id
+
+
+async def update(record_id: int, data: Dict[str, Any]) -> bool:
+    """Update an existing record by ID. Returns True if found and updated."""
+    async with _file_lock:
+        wb, ws = _load_workbook_safe()
+        headers = [cell.value for cell in ws[1]]
+
+        if "id" not in headers:
+            wb.close()
+            return False
+
+        id_col_idx = headers.index("id")
+
+        # Check if new columns need to be added
+        for key in data.keys():
+            if key != "id" and key not in headers:
+                headers.append(key)
+                col_num = len(headers)
+                ws.cell(row=1, column=col_num, value=key)
+
+        # Re-read headers after potential additions
+        headers = [cell.value for cell in ws[1]]
+
+        for row_idx, row in enumerate(ws.iter_rows(min_row=2, values_only=True), start=2):
+            if row[id_col_idx] is not None:
+                try:
+                    if int(row[id_col_idx]) == record_id:
+                        for col_idx, header in enumerate(headers):
+                            if header is not None and header != "id" and header in data:
+                                ws.cell(row=row_idx, column=col_idx + 1, value=data[header])
+                        wb.save(str(_get_file_path()))
+                        wb.close()
+                        return True
+                except (ValueError, TypeError):
+                    pass
+        wb.close()
+        return False
+
+
+async def delete(record_id: int) -> bool:
+    """Delete a record by ID. Returns True if found and deleted."""
+    async with _file_lock:
+        wb, ws = _load_workbook_safe()
+        headers = [cell.value for cell in ws[1]]
+
+        if "id" not in headers:
+            wb.close()
+            return False
+
+        id_col_idx = headers.index("id")
+
+        for row_idx, row in enumerate(ws.iter_rows(min_row=2, values_only=True), start=2):
+            if row[id_col_idx] is not None:
+                try:
+                    if int(row[id_col_idx]) == record_id:
+                        ws.delete_rows(row_idx)
+                        wb.save(str(_get_file_path()))
+                        wb.close()
+                        return True
+                except (ValueError, TypeError):
+                    pass
+        wb.close()
+        return False
+
+
+async def import_data(file_content: bytes, mode: str = "append") -> str:
+    """Import data from an uploaded Excel file.
+
+    Args:
+        file_content: Binary content of the uploaded Excel file.
+        mode: 'append' to add rows, 'overwrite' to replace all data.
+
+    Returns:
+        A status message.
+    """
+    async with _file_lock:
+        # Load uploaded file
+        try:
+            upload_wb = load_workbook(BytesIO(file_content))
+        except Exception as e:
+            raise ValueError(f"无法读取上传的Excel文件: {str(e)}")
+
+        upload_ws = upload_wb.active
+        upload_headers = [cell.value for cell in upload_ws[1]]
+        upload_headers = [h for h in upload_headers if h is not None]
+
+        if not upload_headers:
+            raise ValueError("上传的Excel文件没有有效的表头")
+
+        # Read uploaded data rows
+        upload_data = []
+        for row in upload_ws.iter_rows(min_row=2, values_only=True):
+            if all(v is None for v in row):
+                continue
+            record = {}
+            for i, h in enumerate(upload_headers):
+                val = row[i] if i < len(row) else None
+                record[h] = _cell_value_to_str(val)
+            upload_data.append(record)
+        upload_wb.close()
+
+        if mode == "overwrite":
+            # Create new workbook with uploaded structure
+            wb = Workbook()
+            ws = wb.active
+            ws.title = "Sheet1"
+
+            # Ensure id column
+            if "id" not in upload_headers:
+                final_headers = ["id"] + upload_headers
+            else:
+                final_headers = upload_headers
+
+            ws.append(final_headers)
+
+            # Write data with auto-generated IDs
+            current_id = 1
+            for record in upload_data:
+                row_data = []
+                for h in final_headers:
+                    if h == "id":
+                        if "id" in record and record["id"] is not None:
+                            try:
+                                row_data.append(int(record["id"]))
+                                if int(record["id"]) >= current_id:
+                                    current_id = int(record["id"]) + 1
+                            except (ValueError, TypeError):
+                                row_data.append(current_id)
+                                current_id += 1
+                        else:
+                            row_data.append(current_id)
+                            current_id += 1
+                    else:
+                        row_data.append(record.get(h))
+                ws.append(row_data)
+
+            wb.save(str(_get_file_path()))
+            wb.close()
+            return f"覆盖导入成功，共导入 {len(upload_data)} 条记录"
+
+        else:  # append mode
+            wb, ws = _load_workbook_safe()
+            existing_headers = [cell.value for cell in ws[1]]
+            existing_headers = [h for h in existing_headers if h is not None]
+
+            # Merge headers: add new columns from upload
+            merged_headers = list(existing_headers)
+            for h in upload_headers:
+                if h not in merged_headers and h != "id":
+                    merged_headers.append(h)
+
+            # Ensure id column
+            if "id" not in merged_headers:
+                merged_headers.insert(0, "id")
+
+            # If headers changed, rebuild the worksheet
+            if merged_headers != existing_headers:
+                # Read existing data
+                existing_data = []
+                for row in ws.iter_rows(min_row=2, values_only=True):
+                    if all(v is None for v in row):
+                        continue
+                    record = {}
+                    for i, h in enumerate(existing_headers):
+                        val = row[i] if i < len(row) else None
+                        record[h] = _cell_value_to_str(val)
+                    existing_data.append(record)
+
+                # Recreate workbook
+                wb = Workbook()
+                ws = wb.active
+                ws.title = "Sheet1"
+                ws.append(merged_headers)
+
+                for record in existing_data:
+                    row_data = [record.get(h) for h in merged_headers]
+                    ws.append(row_data)
+            
+            # Get next ID
+            next_id = _get_next_id(ws)
+
+            # Append uploaded data
+            final_headers = [cell.value for cell in ws[1]]
+            for record in upload_data:
+                row_data = []
+                for h in final_headers:
+                    if h == "id":
+                        row_data.append(next_id)
+                        next_id += 1
+                    elif h is not None:
+                        row_data.append(record.get(h))
+                    else:
+                        row_data.append(None)
+                ws.append(row_data)
+
+            wb.save(str(_get_file_path()))
+            wb.close()
+            return f"追加导入成功，共导入 {len(upload_data)} 条记录"
+
+
+def export_data() -> bytes:
+    """Export current data as Excel bytes."""
+    wb, ws = _load_workbook_safe()
+    output = BytesIO()
+    wb.save(output)
+    wb.close()
+    output.seek(0)
+    return output.getvalue()

excel_vis-0.1.0.dist-info/METADATA

@@ -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) 文件。
+
+
+

excel_vis-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+excel_vis/__init__.py,sha256=SXejOEnXfG0yNsckHg0DUd6qc_-52EcTjYIj-i4jHG4,1534
+excel_vis/__main__.py,sha256=iAozqHypcRmnK63_nb0KPFxsL2sTbHtta9mNVEwlu44,132
+excel_vis/app.py,sha256=hQmxHXKTyWRDQA6GhiYUgECxJnkJp7X4lvKODyQOPnw,1535
+excel_vis/cli.py,sha256=v7oHGuqDitDeWiLdpkRnoNJLpiVc6F-piSxtPpfPyD4,1453
+excel_vis/config.py,sha256=vGH-X3lWLEdLTe34GgZJ2MXCLqGZrwHCl0WDePvBpA8,767
+excel_vis/api/__init__.py,sha256=d7XMEse6wwtLORqrQmnhaKMI8KM3lJSzRVE7HVskq1w,19
+excel_vis/api/columns.py,sha256=Ijt6zaWgoHj8pKByaQNpPUsuB7Da_wYNVJWsInWpIro,470
+excel_vis/api/data.py,sha256=XPpSqgYHuzhvHesa2QpO4HuPhZ39rfxfz-Jor8BbXh0,2435
+excel_vis/api/file_ops.py,sha256=6hB2V35gswGGchTv50_Mi5mDJTYdi7zP8wrZEMIxsv8,2455
+excel_vis/services/__init__.py,sha256=_rAF0b_ESOnKNSNRTDgBtv5D6k8lWfwKnOfH0_3aOIw,24
+excel_vis/services/excel_service.py,sha256=1ys4qLpr_DVEWrhtrIaTyRHKCjccjA_qQeiCFPVcAjM,13205
+excel_vis-0.1.0.dist-info/licenses/LICENSE,sha256=vypY5l3jhuff7dyqqcpsxh0s3mR3eevFfq2CuOn5Gh8,1065
+excel_vis-0.1.0.dist-info/METADATA,sha256=7Ffakrlo4xKlKQ6n4BWH9fpLUGCdmMqp06aBl93g8r8,13676
+excel_vis-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+excel_vis-0.1.0.dist-info/entry_points.txt,sha256=rLG5Wxbw1laPV5Vdcb0GxhZsBx8h21pOGbpfO_ayU2s,48
+excel_vis-0.1.0.dist-info/top_level.txt,sha256=-sB2kIq9KXT3Fvi4s3DW1OwbxJjbsvtPyNYpcWhup5o,10
+excel_vis-0.1.0.dist-info/RECORD,,

excel_vis-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

excel_vis-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+excel-vis = excel_vis.cli:app

excel_vis-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+excel_vis