maybeai-sheet-cli 0.14.2__tar.gz → 0.16.0__tar.gz

{maybeai_sheet_cli-0.14.2 → maybeai_sheet_cli-0.16.0}/.gitignore

@@ -24,3 +24,4 @@ temp
 docs_requirement
 artifacts/
 .worktrees/
+docs/requirements

{maybeai_sheet_cli-0.14.2 → maybeai_sheet_cli-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maybeai-sheet-cli
-Version: 0.14.2
+Version: 0.16.0
 Summary: CLI for common MaybeAI spreadsheet operations
 Project-URL: Homepage, https://github.com/OmniMCP-AI/maybeai-sheet-cli
 Project-URL: Repository, https://github.com/OmniMCP-AI/maybeai-sheet-cli
@@ -148,6 +148,49 @@ mbs workbook import ./mixed-workbook.xlsx --engine auto
 mbs workbook import ./mixed-workbook.xlsx --engine "postgres,excel,excel,postgres"
 ```
 
+Import CSV, TSV, or a public Google Sheet through the import-source preview flow:
+
+```bash
+mbs workbook import ./orders.csv
+mbs workbook import ./orders.tsv
+mbs workbook import ./orders.csv --engine postgres
+mbs workbook import ./orders.tsv --engine excelize
+mbs workbook import "https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0"
+mbs workbook import "https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0" --engine postgres
+mbs workbook import "https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0" --source-worksheet-name "1店" --worksheet-name "Store 1" --engine excelize
+mbs workbook import ./orders.csv --preview-only --output json
+```
+
+Append a worksheet from a local Excel file, CSV/TSV file, or public Google Sheet into an existing workbook:
+
+```bash
+mbs workbook import ./report.xlsx --doc-id target123 --worksheet-name "联盟" --engine excelize
+mbs workbook import ./report.xlsx --doc-id target123 --worksheet-name "联盟" --target-worksheet-name "联盟导入" --engine postgres
+mbs workbook import ./orders.csv --doc-id target123 --worksheet-name "orders" --target-worksheet-name "Orders Imported" --engine postgres
+mbs workbook import "https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0" --doc-id target123 --worksheet-name "1店" --engine excelize
+```
+
+Import one source worksheet from another workbook into a raw PG/db-table surface:
+
+```bash
+mbs workbook import \
+  --doc-id target123 \
+  --engine postgres \
+  --source-doc-id source123 \
+  --worksheet-name "1店" \
+  --name R_order_lines_store_1 \
+  --verify \
+  --output json
+```
+
+After a successful raw worksheet import, trust `workbook import` stdout and
+`--verify` as the table-creation evidence. If you need a spot check, sample one
+representative created table instead of looping over every `R_*` table:
+
+```bash
+mbs db-table sample --doc-id target123 --name R_order_lines_store_1 --limit 2 --output json
+```
+
 Append rows and verify:
 
 ```bash
@@ -241,7 +284,7 @@ mbs
 │   ├── source                 PLAN   Similar to NotebookLM source (menu on the left).
 │   ├── create                 NOW    Create a new workbook.
 │   ├── create-from-file       NOW    Import an .xlsx file.
-│   ├── import                 NOW    Preferred alias for create-from-file.
+│   ├── import                 NOW    File import or cross-workbook worksheet -> raw PG surface import.
 │   ├── list-user-workbooks    API    List user workbooks with bounded output.
 │   ├── list-worksheets        API    List worksheets, including engine.
 │   ├── search                 NOW    Search user workbooks with bounded output.
@@ -329,6 +372,12 @@ mbs
 │   ├── validate               NOW    Validate dashboard layout, worksheet target, and chart source fields locally.
 │   └── refresh                NOW    Upsert dashboard charts from one spec and re-verify chart inventory.
 │
+├── pivot
+│   ├── read                   API    Read a pivot result from a JSON spec.
+│   ├── preview                API    Preview pivot output without writing cells.
+│   ├── upsert                 API    Write or overwrite a persisted pivot table at an anchor cell.
+│   └── delete                 API    Delete a persisted pivot table by worksheet and anchor cell.
+│
 │
 ├── excel-worksheet style
 │   ├── cell batch-set          NOW    Apply cell style batches from JSON.
@@ -376,6 +425,13 @@ mbs update --check
 mbs workbook metadata --doc-id abc123  # API
 mbs workbook list-user-workbooks --limit 20  # API
 mbs workbook list-worksheets --doc-id abc123  # API
+mbs workbook import ./report.xlsx  # NOW
+mbs workbook import ./orders.csv --engine postgres  # NOW
+mbs workbook import "https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0" --engine excelize  # NOW
+mbs workbook import ./report.xlsx --doc-id target123 --worksheet-name "联盟" --target-worksheet-name "联盟导入" --engine postgres  # NOW
+mbs workbook import ./orders.csv --doc-id target123 --worksheet-name "orders" --target-worksheet-name "Orders Imported" --engine postgres  # NOW
+mbs workbook import "https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0" --doc-id target123 --worksheet-name "1店" --target-worksheet-name "Store 1" --engine excelize  # NOW
+mbs workbook import --doc-id target123 --engine postgres --source-doc-id source123 --worksheet-name "1店" --name R_order_lines_store_1 --verify --output json  # NOW
 mbs workbook export --doc-id abc123 --out workbook.xlsx  # API
 mbs workbook copy --doc-id abc123 --name "Budget Copy"  # API
 mbs workbook delete --doc-id abc123 --dry-run  # API
@@ -406,7 +462,7 @@ mbs excel-table style columns-width --doc-id abc123 --worksheet-name Orders --ta
 # db-table
 mbs db-table metadata --doc-id abc123 --name orders-large  # API
 mbs db-table schema --doc-id abc123 --name orders-large  # API
-mbs db-table sample --doc-id abc123 --name orders-large --limit 50  # API
+mbs db-table sample --doc-id target123 --name R_order_lines_store_1 --limit 2 --output json  # API, representative post-import spot check
 mbs db-table read --doc-id abc123 --name orders-large --limit 100 --offset 200  # API
 mbs db-table insert --doc-id abc123 --name orders-large --rows rows.json  # API
 mbs db-table create --doc-id abc123 --name Orders --rows orders.json  # API
@@ -479,6 +535,26 @@ mbs excel-worksheet dashboard refresh --doc-id abc123 --spec dashboard.json  # N
 #   ]
 # }
 
+# pivot
+mbs pivot preview --doc-id abc123 --gid 1 --spec pivot.json  # API
+mbs pivot read --doc-id abc123 --spec pivot.json  # API
+mbs pivot upsert --doc-id abc123 --target-worksheet-name PivotResult --anchor-cell A1 --spec pivot.json  # API
+mbs pivot delete --doc-id abc123 --worksheet-name PivotResult --anchor-cell A1 --dry-run  # API
+mbs pivot delete --doc-id abc123 --worksheet-name PivotResult --anchor-cell A1 --yes  # API
+
+# recommended pivot.json shape
+# {
+#   "worksheet_name": "SourceData",
+#   "range_address": "A1:C100",
+#   "row_fields": ["Region"],
+#   "column_fields": ["Category"],
+#   "metrics": [
+#     { "aggregate": "sum", "value_field": "Amount", "label": "Total Amount" }
+#   ],
+#   "show_row_totals": true,
+#   "show_column_totals": true
+# }
+
 # style
 mbs excel-worksheet style freeze-panes --doc-id abc123 --worksheet-name Actuals --cell B2  # NOW
 mbs excel-worksheet style cell batch-set --doc-id abc123 --worksheet-name Actuals --range A1:G1 --style header_style.json  # NOW
@@ -552,6 +628,9 @@ Relationship guide:
   source-backed visualizations.
 - Use `excel-worksheet dashboard` for local validation and worksheet-level chart
   orchestration such as manifest, create-config, and refresh.
+- Use `pivot` for persisted pivot tables. Prefer `pivot preview` before writing,
+  then `pivot upsert` with an explicit `--anchor-cell`; use `pivot delete`
+  instead of manually clearing a pivot spill range.
 - Use `excel-worksheet image` for list/read/insert/replace/delete image
   workflows.
 - Use `version` for workbook history inspection and restore.

{maybeai_sheet_cli-0.14.2 → maybeai_sheet_cli-0.16.0}/README.md

@@ -124,6 +124,49 @@ mbs workbook import ./mixed-workbook.xlsx --engine auto
 mbs workbook import ./mixed-workbook.xlsx --engine "postgres,excel,excel,postgres"
 ```
 
+Import CSV, TSV, or a public Google Sheet through the import-source preview flow:
+
+```bash
+mbs workbook import ./orders.csv
+mbs workbook import ./orders.tsv
+mbs workbook import ./orders.csv --engine postgres
+mbs workbook import ./orders.tsv --engine excelize
+mbs workbook import "https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0"
+mbs workbook import "https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0" --engine postgres
+mbs workbook import "https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0" --source-worksheet-name "1店" --worksheet-name "Store 1" --engine excelize
+mbs workbook import ./orders.csv --preview-only --output json
+```
+
+Append a worksheet from a local Excel file, CSV/TSV file, or public Google Sheet into an existing workbook:
+
+```bash
+mbs workbook import ./report.xlsx --doc-id target123 --worksheet-name "联盟" --engine excelize
+mbs workbook import ./report.xlsx --doc-id target123 --worksheet-name "联盟" --target-worksheet-name "联盟导入" --engine postgres
+mbs workbook import ./orders.csv --doc-id target123 --worksheet-name "orders" --target-worksheet-name "Orders Imported" --engine postgres
+mbs workbook import "https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0" --doc-id target123 --worksheet-name "1店" --engine excelize
+```
+
+Import one source worksheet from another workbook into a raw PG/db-table surface:
+
+```bash
+mbs workbook import \
+  --doc-id target123 \
+  --engine postgres \
+  --source-doc-id source123 \
+  --worksheet-name "1店" \
+  --name R_order_lines_store_1 \
+  --verify \
+  --output json
+```
+
+After a successful raw worksheet import, trust `workbook import` stdout and
+`--verify` as the table-creation evidence. If you need a spot check, sample one
+representative created table instead of looping over every `R_*` table:
+
+```bash
+mbs db-table sample --doc-id target123 --name R_order_lines_store_1 --limit 2 --output json
+```
+
 Append rows and verify:
 
 ```bash
@@ -217,7 +260,7 @@ mbs
 │   ├── source                 PLAN   Similar to NotebookLM source (menu on the left).
 │   ├── create                 NOW    Create a new workbook.
 │   ├── create-from-file       NOW    Import an .xlsx file.
-│   ├── import                 NOW    Preferred alias for create-from-file.
+│   ├── import                 NOW    File import or cross-workbook worksheet -> raw PG surface import.
 │   ├── list-user-workbooks    API    List user workbooks with bounded output.
 │   ├── list-worksheets        API    List worksheets, including engine.
 │   ├── search                 NOW    Search user workbooks with bounded output.
@@ -305,6 +348,12 @@ mbs
 │   ├── validate               NOW    Validate dashboard layout, worksheet target, and chart source fields locally.
 │   └── refresh                NOW    Upsert dashboard charts from one spec and re-verify chart inventory.
 │
+├── pivot
+│   ├── read                   API    Read a pivot result from a JSON spec.
+│   ├── preview                API    Preview pivot output without writing cells.
+│   ├── upsert                 API    Write or overwrite a persisted pivot table at an anchor cell.
+│   └── delete                 API    Delete a persisted pivot table by worksheet and anchor cell.
+│
 │
 ├── excel-worksheet style
 │   ├── cell batch-set          NOW    Apply cell style batches from JSON.
@@ -352,6 +401,13 @@ mbs update --check
 mbs workbook metadata --doc-id abc123  # API
 mbs workbook list-user-workbooks --limit 20  # API
 mbs workbook list-worksheets --doc-id abc123  # API
+mbs workbook import ./report.xlsx  # NOW
+mbs workbook import ./orders.csv --engine postgres  # NOW
+mbs workbook import "https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0" --engine excelize  # NOW
+mbs workbook import ./report.xlsx --doc-id target123 --worksheet-name "联盟" --target-worksheet-name "联盟导入" --engine postgres  # NOW
+mbs workbook import ./orders.csv --doc-id target123 --worksheet-name "orders" --target-worksheet-name "Orders Imported" --engine postgres  # NOW
+mbs workbook import "https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0" --doc-id target123 --worksheet-name "1店" --target-worksheet-name "Store 1" --engine excelize  # NOW
+mbs workbook import --doc-id target123 --engine postgres --source-doc-id source123 --worksheet-name "1店" --name R_order_lines_store_1 --verify --output json  # NOW
 mbs workbook export --doc-id abc123 --out workbook.xlsx  # API
 mbs workbook copy --doc-id abc123 --name "Budget Copy"  # API
 mbs workbook delete --doc-id abc123 --dry-run  # API
@@ -382,7 +438,7 @@ mbs excel-table style columns-width --doc-id abc123 --worksheet-name Orders --ta
 # db-table
 mbs db-table metadata --doc-id abc123 --name orders-large  # API
 mbs db-table schema --doc-id abc123 --name orders-large  # API
-mbs db-table sample --doc-id abc123 --name orders-large --limit 50  # API
+mbs db-table sample --doc-id target123 --name R_order_lines_store_1 --limit 2 --output json  # API, representative post-import spot check
 mbs db-table read --doc-id abc123 --name orders-large --limit 100 --offset 200  # API
 mbs db-table insert --doc-id abc123 --name orders-large --rows rows.json  # API
 mbs db-table create --doc-id abc123 --name Orders --rows orders.json  # API
@@ -455,6 +511,26 @@ mbs excel-worksheet dashboard refresh --doc-id abc123 --spec dashboard.json  # N
 #   ]
 # }
 
+# pivot
+mbs pivot preview --doc-id abc123 --gid 1 --spec pivot.json  # API
+mbs pivot read --doc-id abc123 --spec pivot.json  # API
+mbs pivot upsert --doc-id abc123 --target-worksheet-name PivotResult --anchor-cell A1 --spec pivot.json  # API
+mbs pivot delete --doc-id abc123 --worksheet-name PivotResult --anchor-cell A1 --dry-run  # API
+mbs pivot delete --doc-id abc123 --worksheet-name PivotResult --anchor-cell A1 --yes  # API
+
+# recommended pivot.json shape
+# {
+#   "worksheet_name": "SourceData",
+#   "range_address": "A1:C100",
+#   "row_fields": ["Region"],
+#   "column_fields": ["Category"],
+#   "metrics": [
+#     { "aggregate": "sum", "value_field": "Amount", "label": "Total Amount" }
+#   ],
+#   "show_row_totals": true,
+#   "show_column_totals": true
+# }
+
 # style
 mbs excel-worksheet style freeze-panes --doc-id abc123 --worksheet-name Actuals --cell B2  # NOW
 mbs excel-worksheet style cell batch-set --doc-id abc123 --worksheet-name Actuals --range A1:G1 --style header_style.json  # NOW
@@ -528,6 +604,9 @@ Relationship guide:
   source-backed visualizations.
 - Use `excel-worksheet dashboard` for local validation and worksheet-level chart
   orchestration such as manifest, create-config, and refresh.
+- Use `pivot` for persisted pivot tables. Prefer `pivot preview` before writing,
+  then `pivot upsert` with an explicit `--anchor-cell`; use `pivot delete`
+  instead of manually clearing a pivot spill range.
 - Use `excel-worksheet image` for list/read/insert/replace/delete image
   workflows.
 - Use `version` for workbook history inspection and restore.

{maybeai_sheet_cli-0.14.2 → maybeai_sheet_cli-0.16.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "maybeai-sheet-cli"
-version = "0.14.2"
+version = "0.16.0"
 description = "CLI for common MaybeAI spreadsheet operations"
 readme = "README.md"
 requires-python = ">=3.10"

maybeai_sheet_cli-0.16.0/src/maybeai_sheet/__init__.py

@@ -0,0 +1,44 @@
+"""MaybeAI Sheet CLI package."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version as metadata_version
+from pathlib import Path
+
+__all__ = ["__version__"]
+
+_PACKAGE_NAME = "maybeai-sheet-cli"
+
+
+def _version_from_pyproject() -> str | None:
+    pyproject = Path(__file__).resolve().parents[2] / "pyproject.toml"
+    if not pyproject.is_file():
+        return None
+
+    in_project_section = False
+
+    for line in pyproject.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if stripped == "[project]":
+            in_project_section = True
+            continue
+        if in_project_section and stripped.startswith("["):
+            break
+        if in_project_section and stripped.startswith("version"):
+            return stripped.split("=", 1)[1].strip().strip('"')
+
+    raise RuntimeError(f"Could not determine {_PACKAGE_NAME} version from {pyproject}.")
+
+
+def _resolve_version() -> str:
+    source_version = _version_from_pyproject()
+    if source_version is not None:
+        return source_version
+
+    try:
+        return metadata_version(_PACKAGE_NAME)
+    except PackageNotFoundError:
+        return "0+unknown"
+
+
+__version__ = _resolve_version()

{maybeai_sheet_cli-0.14.2 → maybeai_sheet_cli-0.16.0}/src/maybeai_sheet/client.py

@@ -126,3 +126,35 @@ class MaybeAIClient:
             files["file"][1].close()
         self._raise_for_error(response, endpoint=endpoint)
         return response.json()
+
+    def post_multipart(
+        self,
+        path: str,
+        *,
+        data: dict[str, str],
+        file_path: Path | None = None,
+        file_field: str = "file",
+        content_type: str | None = None,
+    ) -> dict[str, Any]:
+        endpoint = self._endpoint(path)
+        files: dict[str, tuple[str, Any] | tuple[str, Any, str]] | None = None
+        file_handle = None
+        if file_path is not None:
+            file_handle = file_path.open("rb")
+            if content_type:
+                files = {file_field: (file_path.name, file_handle, content_type)}
+            else:
+                files = {file_field: (file_path.name, file_handle)}
+        try:
+            with self._client() as client:
+                response = client.post(
+                    endpoint,
+                    headers=self._headers(content_type=False),
+                    files=files,
+                    data=data,
+                )
+        finally:
+            if file_handle is not None:
+                file_handle.close()
+        self._raise_for_error(response, endpoint=endpoint)
+        return response.json()