sheet/inspect.py
Inspect spreadsheet workbooks (XLSX, ODS), listing sheet names, row and column dimensions, and header columns.
Use when the user wants to see the structure, sheets, dimensions, or column names of an Excel or ODS spreadsheet without reading all rows.
- the file
- sheet/inspect.py
- its skill
- sheet/SKILL.md (the whole sheet pack)
- as knowledge
- okf/sheet/inspect.md
- on GitHub
- sheet/inspect.py ↗
Run it
1. Once per machine: install fragletc (Docker must already be running).
curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh
2. Fetch the tool and print its contract.
curl -fsSLO https://tools.ofthemachine.com/sheet/inspect.py && chmod +x inspect.py && ./inspect.py --fraglet-help
3. Run it.
./inspect.py -p workbook="<workbook>" [-p format=markdown]
Parameters
| name | type | requirement | description |
|---|---|---|---|
| workbook | file | required | Spreadsheet workbook mounted at /input/workbook |
| format | string | default markdown | Output format: markdown or json |
Outputs
stdout
Provenance
- image
- ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522
- reach
network=none— a run is a pure function of its inputs; results are safe to memoize.- procedure_hash
- sha256:78e22335f0414ecb2b33794512af5e34218a2c3d24a186a4d7823a8c1f2b05bb
- receipt
- add
--receipt run.jsonto any run;receipt/attest.pyverifies it against this hash without re-running.
Source
inspect.py · 103 lines · sha256 78e22335f041…
#!/usr/bin/env -S fragletc --image ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522
#: d=Inspect spreadsheet workbooks (XLSX, ODS), listing sheet names, row and column dimensions, and header columns.
#: when=Use when the user wants to see the structure, sheets, dimensions, or column names of an Excel or ODS spreadsheet without reading all rows.
#: network=none
#: stdin=none
#: param=workbook:required:file:d=Spreadsheet workbook mounted at /input/workbook
#: param=format:default=markdown:d=Output format: markdown or json
import json
import os
import sys
import zipfile
import openpyxl
from tabulate import tabulate
wb_path = os.environ.get("WORKBOOK", "")
fmt = os.environ["FORMAT"].strip().lower()
if not wb_path or not os.path.exists(wb_path):
print(f"Error: workbook file '{wb_path}' does not exist", file=sys.stderr)
sys.exit(1)
if fmt not in ("markdown", "json"):
print(f"Error: unknown format '{fmt}' (expected markdown or json)", file=sys.stderr)
sys.exit(1)
def is_ods(path: str) -> bool:
try:
with zipfile.ZipFile(path) as zf:
return "content.xml" in zf.namelist() and "mimetype" in zf.namelist()
except Exception:
return False
sheets_info = []
if is_ods(wb_path):
from odf import teletype, table
from odf.opendocument import load
doc = load(wb_path)
for idx, sheet in enumerate(doc.getElementsByType(table.Table), start=1):
name = sheet.getAttribute("name") or f"Sheet{idx}"
rows = sheet.getElementsByType(table.TableRow)
header = []
for r in rows:
cells = [teletype.extractText(c).strip() for c in r.getElementsByType(table.TableCell)]
if any(cells):
header = [c or f"Col_{i+1}" for i, c in enumerate(cells)]
break
sheets_info.append({
"index": idx,
"name": name,
"rows": len(rows),
"columns": len(header),
"headers": header,
})
else:
try:
with open(wb_path, "rb") as handle:
wb = openpyxl.load_workbook(handle, data_only=True, read_only=True)
for idx, name in enumerate(wb.sheetnames, start=1):
ws = wb[name]
header = []
row_count = ws.max_row or 0
col_count = ws.max_column or 0
for r in ws.iter_rows(values_only=True):
str_cells = ["" if c is None else str(c).strip() for c in r]
if any(str_cells):
header = [c or f"Col_{i+1}" for i, c in enumerate(str_cells)]
break
sheets_info.append({
"index": idx,
"name": name,
"rows": row_count,
"columns": col_count or len(header),
"headers": header,
})
except Exception as e:
print(f"Error: failed to open workbook as Excel XLSX or ODS: {e}", file=sys.stderr)
sys.exit(1)
if not sheets_info:
print("Workbook has no sheets.", file=sys.stderr)
sys.exit(1)
if fmt == "json":
print(json.dumps(sheets_info, indent=2))
else:
table_rows = []
for s in sheets_info:
hdr_preview = ", ".join(s["headers"][:6])
if len(s["headers"]) > 6:
hdr_preview += f", ... (+{len(s['headers']) - 6} more)"
table_rows.append([
s["index"],
s["name"],
s["rows"],
s["columns"],
hdr_preview or "(empty)"
])
print(tabulate(table_rows, headers=["#", "Sheet Name", "Rows", "Cols", "Header Preview"], tablefmt="github"))