excel-explorer 0.1.0__tar.gz

excel_explorer-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/
+.coverage
+.claude/

excel_explorer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 PressW LLC
+
+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_explorer-0.1.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: excel-explorer
+Version: 0.1.0
+Summary: CLI tool for exploring Excel workbooks — trace formulas, understand model structure, read data
+Project-URL: Homepage, https://github.com/pressw-llc/excel-explorer
+Project-URL: Repository, https://github.com/pressw-llc/excel-explorer
+Project-URL: Issues, https://github.com/pressw-llc/excel-explorer/issues
+Author-email: PressW LLC <dev@pressw.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,dependency-graph,excel,financial-model,formula,xlsx
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: formulas>=1.3
+Requires-Dist: openpyxl>=3.1
+Description-Content-Type: text/markdown
+
+# Excel Explorer
+
+CLI tool for exploring Excel workbooks. Trace formula dependencies, understand model structure, read data with pagination. Designed for use by Claude Code agents.
+
+## Install
+
+```bash
+# As a standalone CLI tool (recommended)
+uv tool install excel-explorer
+
+# Or with pip
+pip install excel-explorer
+
+# Or run without installing
+uvx --from excel-explorer xlx overview "file.xlsx"
+```
+
+This installs the `xlx` command.
+
+### Development setup
+
+```bash
+git clone https://github.com/pressw-llc/excel-explorer.git
+cd excel-explorer
+uv sync --group dev
+uv run pytest
+```
+
+## Usage
+
+Every command takes a workbook path as its first argument. Paths with spaces should be quoted.
+
+### Orientation
+
+Get a high-level view of a workbook before diving into details.
+
+```bash
+# Workbook overview: sheets, dimensions, formula counts, named ranges
+xlx overview "Financials.xlsx"
+
+# Describe a single sheet: headers, merged cells, data regions
+xlx describe "Financials.xlsx" "Balance Sheet"
+
+# List all named ranges and their targets
+xlx named-ranges "Financials.xlsx"
+```
+
+### Reading
+
+Read cell values and structured data from sheets.
+
+```bash
+# Read a range (values only)
+xlx read "Financials.xlsx" "Income Statement" A1:D20
+
+# Read a range showing formulas alongside computed values
+xlx read --formulas "Financials.xlsx" "Income Statement" A1:D20
+
+# Read a full row with auto-detected headers
+xlx read-row "Financials.xlsx" "Income Statement" 5
+
+# Read a full column
+xlx read-col "Financials.xlsx" "Income Statement" B
+
+# Auto-detect contiguous table regions on a sheet
+xlx tables "Financials.xlsx" "Income Statement"
+```
+
+### Dependencies
+
+Understand how cells relate to each other and trace formula chains.
+
+```bash
+# Trace a cell's dependency tree down to leaf inputs
+xlx trace "Financials.xlsx" "Income Statement!B10"
+xlx trace "Financials.xlsx" B10 --sheet "Income Statement"
+
+# Find all cells that depend on a given cell (reverse trace)
+xlx dependents "Financials.xlsx" "Assumptions!C5"
+
+# Show unique formula patterns on a sheet, grouped by structure
+xlx formula-map "Financials.xlsx" "Income Statement"
+
+# Find hardcoded cells that other cells depend on (model inputs/assumptions)
+xlx find-inputs "Financials.xlsx"
+xlx find-inputs "Financials.xlsx" --sheet "Assumptions"
+
+# Map which sheets reference which other sheets
+xlx sheet-flow "Financials.xlsx"
+```
+
+### Financial Analysis
+
+Higher-level commands built for financial models.
+
+```bash
+# Find and summarize assumption sheets and named ranges
+xlx summarize-assumptions "Financials.xlsx"
+
+# Read a time-series row and compute period-over-period changes
+xlx compare-periods "Financials.xlsx" "Income Statement" 10
+
+# Detect formula pattern breaks (hardcoded values in formula rows, etc.)
+xlx find-anomalies "Financials.xlsx" "Income Statement"
+
+# Check that Assets = Liabilities + Equity across all period columns
+xlx validate-balance "Financials.xlsx" "Balance Sheet"
+```
+
+### Search
+
+Search across the entire workbook.
+
+```bash
+# Search all cells for a value or text pattern
+xlx search "Financials.xlsx" "revenue"
+
+# Also search inside formula strings
+xlx search --formulas "Financials.xlsx" "VLOOKUP"
+
+# Report cells with notable formatting: bold, fill colors, borders
+xlx find-formatting "Financials.xlsx" "Income Statement"
+```
+
+## Pagination
+
+Large workbooks can return a lot of data. Use these flags to page through results without overwhelming the context window.
+
+| Flag | Default | Description |
+|---|---|---|
+| `--limit N` | 50 | Maximum number of rows (or items) to return |
+| `--offset N` | 0 | Skip the first N rows before returning results |
+| `--max-cols N` | 20 | Maximum number of columns to show |
+| `--col-offset N` | 0 | Skip the first N columns before returning results |
+| `--depth N` | 5 | Maximum recursion depth for `trace` and `dependents` |
+
+Example — page through a large sheet in chunks of 100 rows (use a bounded
+row range; column-only ranges like `A:Z` are returned column-major and don't
+paginate by row):
+
+```bash
+xlx read "Financials.xlsx" "Transactions" A1:Z1000 --limit 100 --offset 0
+xlx read "Financials.xlsx" "Transactions" A1:Z1000 --limit 100 --offset 100
+xlx read "Financials.xlsx" "Transactions" A1:Z1000 --limit 100 --offset 200
+```
+
+## Output Format
+
+Every command outputs a metadata header followed by `---` and then the body. The header uses a YAML-style `key: value` format describing what was returned so agents can make pagination decisions without re-reading. For example, `xlx read`:
+
+```
+file: financial_model.xlsx
+sheet: P&L
+range: A1:C5
+showing: rows 1-5 of 5
+truncated: false
+---
+  A1: Profit & Loss Statement
+  A3: Line Item
+  A4: Gross Revenue
+  B4: ='Revenue Build'!B8
+  C4: ='Revenue Build'!C8
+  ...
+```
+
+The exact header keys vary by command (`range`, `row`, `column`, `query`, `matches`, ...). The pagination-relevant ones:
+
+- `showing: rows X-Y of Z` — current window and total rows available
+- `truncated: true` — results were cut off; advance `--offset` or increase `--limit`
+- `shown` / `offset` / `limit` — pagination position on search-style commands
+
+Commands that return summaries rather than rows (`overview`, `named-ranges`, `sheet-flow`, `validate-balance`, `trace`, `dependents`) don't paginate and omit these fields.

excel_explorer-0.1.0/README.md

@@ -0,0 +1,172 @@
+# Excel Explorer
+
+CLI tool for exploring Excel workbooks. Trace formula dependencies, understand model structure, read data with pagination. Designed for use by Claude Code agents.
+
+## Install
+
+```bash
+# As a standalone CLI tool (recommended)
+uv tool install excel-explorer
+
+# Or with pip
+pip install excel-explorer
+
+# Or run without installing
+uvx --from excel-explorer xlx overview "file.xlsx"
+```
+
+This installs the `xlx` command.
+
+### Development setup
+
+```bash
+git clone https://github.com/pressw-llc/excel-explorer.git
+cd excel-explorer
+uv sync --group dev
+uv run pytest
+```
+
+## Usage
+
+Every command takes a workbook path as its first argument. Paths with spaces should be quoted.
+
+### Orientation
+
+Get a high-level view of a workbook before diving into details.
+
+```bash
+# Workbook overview: sheets, dimensions, formula counts, named ranges
+xlx overview "Financials.xlsx"
+
+# Describe a single sheet: headers, merged cells, data regions
+xlx describe "Financials.xlsx" "Balance Sheet"
+
+# List all named ranges and their targets
+xlx named-ranges "Financials.xlsx"
+```
+
+### Reading
+
+Read cell values and structured data from sheets.
+
+```bash
+# Read a range (values only)
+xlx read "Financials.xlsx" "Income Statement" A1:D20
+
+# Read a range showing formulas alongside computed values
+xlx read --formulas "Financials.xlsx" "Income Statement" A1:D20
+
+# Read a full row with auto-detected headers
+xlx read-row "Financials.xlsx" "Income Statement" 5
+
+# Read a full column
+xlx read-col "Financials.xlsx" "Income Statement" B
+
+# Auto-detect contiguous table regions on a sheet
+xlx tables "Financials.xlsx" "Income Statement"
+```
+
+### Dependencies
+
+Understand how cells relate to each other and trace formula chains.
+
+```bash
+# Trace a cell's dependency tree down to leaf inputs
+xlx trace "Financials.xlsx" "Income Statement!B10"
+xlx trace "Financials.xlsx" B10 --sheet "Income Statement"
+
+# Find all cells that depend on a given cell (reverse trace)
+xlx dependents "Financials.xlsx" "Assumptions!C5"
+
+# Show unique formula patterns on a sheet, grouped by structure
+xlx formula-map "Financials.xlsx" "Income Statement"
+
+# Find hardcoded cells that other cells depend on (model inputs/assumptions)
+xlx find-inputs "Financials.xlsx"
+xlx find-inputs "Financials.xlsx" --sheet "Assumptions"
+
+# Map which sheets reference which other sheets
+xlx sheet-flow "Financials.xlsx"
+```
+
+### Financial Analysis
+
+Higher-level commands built for financial models.
+
+```bash
+# Find and summarize assumption sheets and named ranges
+xlx summarize-assumptions "Financials.xlsx"
+
+# Read a time-series row and compute period-over-period changes
+xlx compare-periods "Financials.xlsx" "Income Statement" 10
+
+# Detect formula pattern breaks (hardcoded values in formula rows, etc.)
+xlx find-anomalies "Financials.xlsx" "Income Statement"
+
+# Check that Assets = Liabilities + Equity across all period columns
+xlx validate-balance "Financials.xlsx" "Balance Sheet"
+```
+
+### Search
+
+Search across the entire workbook.
+
+```bash
+# Search all cells for a value or text pattern
+xlx search "Financials.xlsx" "revenue"
+
+# Also search inside formula strings
+xlx search --formulas "Financials.xlsx" "VLOOKUP"
+
+# Report cells with notable formatting: bold, fill colors, borders
+xlx find-formatting "Financials.xlsx" "Income Statement"
+```
+
+## Pagination
+
+Large workbooks can return a lot of data. Use these flags to page through results without overwhelming the context window.
+
+| Flag | Default | Description |
+|---|---|---|
+| `--limit N` | 50 | Maximum number of rows (or items) to return |
+| `--offset N` | 0 | Skip the first N rows before returning results |
+| `--max-cols N` | 20 | Maximum number of columns to show |
+| `--col-offset N` | 0 | Skip the first N columns before returning results |
+| `--depth N` | 5 | Maximum recursion depth for `trace` and `dependents` |
+
+Example — page through a large sheet in chunks of 100 rows (use a bounded
+row range; column-only ranges like `A:Z` are returned column-major and don't
+paginate by row):
+
+```bash
+xlx read "Financials.xlsx" "Transactions" A1:Z1000 --limit 100 --offset 0
+xlx read "Financials.xlsx" "Transactions" A1:Z1000 --limit 100 --offset 100
+xlx read "Financials.xlsx" "Transactions" A1:Z1000 --limit 100 --offset 200
+```
+
+## Output Format
+
+Every command outputs a metadata header followed by `---` and then the body. The header uses a YAML-style `key: value` format describing what was returned so agents can make pagination decisions without re-reading. For example, `xlx read`:
+
+```
+file: financial_model.xlsx
+sheet: P&L
+range: A1:C5
+showing: rows 1-5 of 5
+truncated: false
+---
+  A1: Profit & Loss Statement
+  A3: Line Item
+  A4: Gross Revenue
+  B4: ='Revenue Build'!B8
+  C4: ='Revenue Build'!C8
+  ...
+```
+
+The exact header keys vary by command (`range`, `row`, `column`, `query`, `matches`, ...). The pagination-relevant ones:
+
+- `showing: rows X-Y of Z` — current window and total rows available
+- `truncated: true` — results were cut off; advance `--offset` or increase `--limit`
+- `shown` / `offset` / `limit` — pagination position on search-style commands
+
+Commands that return summaries rather than rows (`overview`, `named-ranges`, `sheet-flow`, `validate-balance`, `trace`, `dependents`) don't paginate and omit these fields.

excel_explorer-0.1.0/pyproject.toml

@@ -0,0 +1,86 @@
+[project]
+name = "excel-explorer"
+version = "0.1.0"
+description = "CLI tool for exploring Excel workbooks — trace formulas, understand model structure, read data"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "PressW LLC", email = "dev@pressw.ai" },
+]
+keywords = ["excel", "xlsx", "cli", "financial-model", "formula", "dependency-graph"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Spreadsheet",
+]
+dependencies = [
+    "click>=8.0",
+    "openpyxl>=3.1",
+    "formulas>=1.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/pressw-llc/excel-explorer"
+Repository = "https://github.com/pressw-llc/excel-explorer"
+Issues = "https://github.com/pressw-llc/excel-explorer/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+]
+
+[project.scripts]
+xlx = "excel_explorer.cli:cli"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/excel_explorer"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/excel_explorer", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+version_variables = ["src/excel_explorer/__init__.py:__version__"]
+branch = "main"
+# Stay on the 0.x line: without this, PSR's first release jumps straight to
+# 1.0.0. With it, a feat bumps 0.0.0 -> 0.1.0 and breaking changes bump the
+# minor (not the major) until you intentionally cut 1.0.0.
+allow_zero_version = true
+major_on_zero = false
+# PSR's Docker action runs this in its own container, so it must NOT produce the
+# distribution artifacts we publish — those would be stranded inside the container.
+# Instead we only refresh uv.lock to match the bumped version (committed via
+# `assets`), and build + publish on the runner after PSR tags (see release.yml).
+build_command = "python -m pip install uv && uv lock"
+assets = ["uv.lock"]
+commit_message = "chore(release): {version}"
+tag_format = "v{version}"
+
+[tool.semantic_release.changelog]
+template_dir = ".github/changelog"
+exclude_commit_patterns = ["chore\\(release\\)"]
+
+[tool.semantic_release.remote]
+type = "github"
+token = { env = "GH_TOKEN" }
+
+[tool.semantic_release.commit_parser_options]
+allowed_tags = ["build", "chore", "ci", "docs", "feat", "fix", "perf", "refactor", "style", "test"]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]

excel_explorer-0.1.0/src/excel_explorer/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"