sheetwright 0.1.0__py3-none-any.whl

sheetwright/commands/import_cmd.py

@@ -0,0 +1,96 @@
+"""Implementation of `sheetwright import`."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import click
+
+from sheetwright.exceptions import ProjectError, StaleSessionFormatError
+from sheetwright.project import Project
+from sheetwright.reimport import archive_xlsx
+from sheetwright.security import SecurityLimits, get_operator_limits
+from sheetwright.source.writer import write_source
+from sheetwright.xlsx.flatten import (
+    detect_external_refs,
+    flatten_external_refs,
+)
+from sheetwright.xlsx.reader import read_xlsx
+
+
+def run(
+    *,
+    xlsx_path: Optional[str],
+    project_path: str,
+    archive: bool,
+    flatten: bool,
+    non_interactive: bool,
+    apply: bool,
+    abort: bool,
+    force: bool,
+) -> None:
+    project_root = Path(project_path).resolve()
+
+    try:
+        project = Project.open(project_root)
+    except ProjectError as e:
+        raise click.ClickException(str(e))
+
+    if abort:
+        from sheetwright.reimport import clear_session
+
+        clear_session(project.reimport_session_path)
+        click.echo('Session cleared.')
+        return
+
+    if apply:
+        from sheetwright.reimport import apply_session
+
+        try:
+            apply_session(project, archive=archive, flatten=flatten)
+        except StaleSessionFormatError as e:
+            raise click.ClickException(str(e))
+        return
+
+    if xlsx_path is None:
+        raise click.ClickException(
+            'Missing XLSX argument. Pass a path, or use --apply / --abort '
+            'to act on a staged session.'
+        )
+    xlsx = Path(xlsx_path).resolve()
+
+    if project.has_source():
+        from sheetwright.reimport import do_reimport
+
+        do_reimport(
+            project,
+            xlsx,
+            archive=archive,
+            flatten=flatten,
+            non_interactive=non_interactive,
+            force=force,
+        )
+        return
+
+    limits = SecurityLimits.effective(
+        get_operator_limits(), project.config.security
+    )
+    extrefs = detect_external_refs(xlsx, limits=limits)
+    if extrefs and not flatten:
+        raise click.ClickException(
+            'Workbook contains external references; '
+            'pass --flatten to replace them with cached values, '
+            'or resolve them in Excel before importing.\n'
+            'First few: ' + ', '.join(extrefs[:3])
+        )
+
+    wb = read_xlsx(xlsx, limits=limits)
+    if flatten:
+        flatten_external_refs(wb, xlsx, limits=limits)
+    write_source(wb, project_root)
+
+    if archive:
+        archive_xlsx(xlsx, project_root)
+
+    click.echo(f'Imported {xlsx} into {project_root}')

sheetwright/commands/init_cmd.py

@@ -0,0 +1,52 @@
+"""Implementation of `sheetwright init`."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+DEFAULT_SHEETWRIGHT_TOML = """\
+[project]
+name = "my-model"
+
+[build]
+calc_engine = "libreoffice"
+"""
+
+DEFAULT_WORKBOOK_TOML = """\
+[workbook]
+name = "my-model"
+
+# Sheets are listed in workbook order. Each entry must match a file in sheets/
+# (without the .md/.yaml extension).
+sheets = []
+
+# Workbook-scoped named ranges:
+# [[named_ranges]]
+# name = "growth_rate"
+# scope = "workbook"
+# ref = "Assumptions!B5"
+"""
+
+DEFAULT_GITIGNORE = """\
+build/
+.sheetwright/
+"""
+
+
+def run(path: str) -> None:
+    project = Path(path).resolve()
+    if project.exists() and any(project.iterdir()):
+        raise click.ClickException(f'{project} is not empty.')
+
+    project.mkdir(parents=True, exist_ok=True)
+    (project / 'sheets').mkdir()
+    (project / 'data').mkdir()
+    (project / 'tests').mkdir()
+    (project / 'tests' / '__init__.py').write_text('')
+    (project / 'sheetwright.toml').write_text(DEFAULT_SHEETWRIGHT_TOML)
+    (project / 'workbook.toml').write_text(DEFAULT_WORKBOOK_TOML)
+    (project / '.gitignore').write_text(DEFAULT_GITIGNORE)
+
+    click.echo(f'Initialised sheetwright project at {project}')

sheetwright/commands/mcp_cmd.py

@@ -0,0 +1,10 @@
+"""Implementation of `sheetwright mcp`."""
+
+from __future__ import annotations
+
+
+def run() -> None:
+    from sheetwright.mcp import build_server
+
+    server = build_server()
+    server.run(transport='stdio')

sheetwright/commands/recalc_cmd.py

@@ -0,0 +1,52 @@
+"""Implementation of `sheetwright recalc`."""
+
+from __future__ import annotations
+
+
+import click
+
+from sheetwright.calc import get_calc_engine
+from sheetwright.calc.cache import (
+    hash_xlsx,
+    read_cached,
+    write_cached,
+)
+from sheetwright.exceptions import ProjectError
+from sheetwright.project import Project
+from sheetwright.security import SecurityLimits, get_operator_limits
+
+
+CACHE_HIT_MESSAGE = 'cache hit'
+
+
+def run(*, project_path: str, force: bool) -> None:
+    try:
+        project = Project.open(project_path)
+    except ProjectError as e:
+        raise click.ClickException(str(e))
+
+    from sheetwright.external_edit import warn_if_externally_edited
+
+    warn_if_externally_edited(project)
+
+    cfg = project.config
+    built = project.build_dir / f'{cfg.name}.xlsx'
+    if not built.is_file():
+        raise click.ClickException(
+            f'No built xlsx at {built}. Run `sheetwright build` first.'
+        )
+
+    key = hash_xlsx(built)
+    if not force:
+        cached = read_cached(project.calc_cache_dir, key)
+        if cached is not None:
+            click.echo(f'{CACHE_HIT_MESSAGE}: {key[:12]}')
+            return
+
+    limits = SecurityLimits.effective(
+        get_operator_limits(), project.config.security
+    )
+    engine = get_calc_engine(cfg.calc_engine)
+    result = engine.evaluate(built, limits=limits)
+    path = write_cached(project.calc_cache_dir, key, result)
+    click.echo(f'recalculated: {path}')

sheetwright/commands/snapshot_cmd.py

@@ -0,0 +1,74 @@
+"""Implementation of `sheetwright snapshot`."""
+
+from __future__ import annotations
+
+import click
+
+from sheetwright.calc import get_calc_engine
+from sheetwright.calc.cache import (
+    hash_xlsx,
+    read_cached,
+    write_cached,
+)
+from sheetwright.exceptions import ProjectError
+from sheetwright.project import Project
+from sheetwright.security import SecurityLimits, get_operator_limits
+from sheetwright.snapshot import (
+    Snapshot,
+    diff_snapshots,
+    snapshot_from_calc_result,
+)
+from sheetwright.source.reader import read_source
+
+
+def run(*, project_path: str, update: bool) -> None:
+    try:
+        project = Project.open(project_path)
+    except ProjectError as e:
+        raise click.ClickException(str(e))
+
+    from sheetwright.external_edit import warn_if_externally_edited
+
+    warn_if_externally_edited(project)
+
+    cfg = project.config
+    built = project.build_dir / f'{cfg.name}.xlsx'
+    if not built.is_file():
+        raise click.ClickException(
+            f'No built xlsx at {built}. Run `sheetwright build` first.'
+        )
+
+    limits = SecurityLimits.effective(
+        get_operator_limits(), project.config.security
+    )
+    key = hash_xlsx(built)
+    cached = read_cached(project.calc_cache_dir, key)
+    if cached is None:
+        cached = get_calc_engine(cfg.calc_engine).evaluate(
+            built, limits=limits
+        )
+        write_cached(project.calc_cache_dir, key, cached)
+
+    workbook = read_source(project.root)
+    current = snapshot_from_calc_result(cached, workbook)
+    snap_path = project.snapshots_dir / f'{cfg.name}.json'
+
+    if not snap_path.is_file():
+        current.write(snap_path)
+        click.echo(f'initialized snapshot at {snap_path}')
+        return
+
+    if update:
+        current.write(snap_path)
+        click.echo(f'updated snapshot at {snap_path}')
+        return
+
+    saved = Snapshot.read(snap_path)
+    diffs = diff_snapshots(saved, current)
+    if not diffs:
+        click.echo('no changes')
+        return
+
+    for sheet, addr, old, new in diffs:
+        click.echo(f'  {sheet}!{addr}: {old!r} -> {new!r}')
+    raise click.exceptions.Exit(1)

sheetwright/commands/test_cmd.py

@@ -0,0 +1,133 @@
+"""Implementation of `sheetwright test` (testsweet, in-process).
+
+Uses testsweet's lower-level `discover` + `run` API directly so we
+can run user tests without mutating the process's cwd. This matters
+for long-running hosts (the MCP server in particular).
+
+User projects lose support for `[tool.testsweet.discovery]` in their
+`pyproject.toml` via this command — we walk `tests/test_*.py` (and
+honour `targets` if given) and import each file ourselves. Users who
+want `[tool.testsweet.discovery]` can `python -m testsweet` from
+their project root directly.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from typing import Sequence
+
+import click
+from testsweet import (
+    Errored,
+    Failed,
+    Passed,
+    Skipped,
+    XFailed,
+    XPassed,
+    run as ts_run,
+)
+
+from sheetwright.exceptions import ProjectError
+from sheetwright.project import Project
+from sheetwright.security import PathOutsideProjectError, resolve_under
+
+
+def run(*, project_path: str, targets: Sequence[str]) -> None:
+    try:
+        project = Project.open(project_path)
+    except ProjectError as e:
+        raise click.ClickException(str(e))
+
+    if not project.tests_dir.is_dir():
+        raise click.ClickException(f'no tests/ directory in {project.root}')
+
+    test_files = list(_resolve_targets(project, list(targets)))
+    if not test_files:
+        click.echo('no tests collected')
+        return
+
+    saved_path = list(sys.path)
+    saved_modules = {
+        name: mod
+        for name, mod in sys.modules.items()
+        if name == '_user_tests' or name.startswith('_user_tests.')
+    }
+    sys.path.insert(0, str(project.root))
+    try:
+        any_failure = False
+        for test_file in test_files:
+            module = _import_module(test_file)
+            for name, outcome in ts_run(module):
+                full = f'{test_file.relative_to(project.root)}::{name}'
+                match outcome:
+                    case Passed():
+                        click.echo(f'{full} ... ok')
+                    case Skipped(reason=reason):
+                        click.echo(f'{full} ... skipped: {reason}')
+                    case XFailed(reason=reason):
+                        click.echo(f'{full} ... xfail: {reason}')
+                    case XPassed(reason=reason):
+                        any_failure = True
+                        click.echo(f'{full} ... XPASS: {reason}')
+                    case Failed(exc=exc):
+                        any_failure = True
+                        click.echo(
+                            f'{full} ... FAIL: {type(exc).__name__}: {exc}'
+                        )
+                    case Errored(exc=exc):
+                        any_failure = True
+                        click.echo(
+                            f'{full} ... ERROR: {type(exc).__name__}: {exc}'
+                        )
+    finally:
+        sys.path[:] = saved_path
+        # Restore any pre-existing _user_tests modules we may have
+        # shadowed; remove ones we created.
+        for name in [
+            n
+            for n in sys.modules
+            if n == '_user_tests' or n.startswith('_user_tests.')
+        ]:
+            del sys.modules[name]
+        sys.modules.update(saved_modules)
+
+    if any_failure:
+        raise click.exceptions.Exit(1)
+
+
+def _resolve_targets(project: Project, targets: list[str]) -> list[Path]:
+    """Return the list of test files to run.
+
+    Targets are resolved relative to project.root (so users can pass
+    'tests/test_foo.py'). The resolved path must fall under tests_dir.
+    """
+    if not targets:
+        return sorted(project.tests_dir.rglob('test_*.py'))
+    out = []
+    for t in targets:
+        p = resolve_under(project.root, t)
+        if not p.is_relative_to(project.tests_dir):
+            raise PathOutsideProjectError(
+                f'{t!r} resolves outside {project.tests_dir!r}'
+            )
+        if p.is_file():
+            out.append(p)
+        elif p.is_dir():
+            out.extend(sorted(p.rglob('test_*.py')))
+        else:
+            raise click.ClickException(f'no such target: {t}')
+    return out
+
+
+def _import_module(path: Path):
+    """Import a test file under a stable namespace."""
+    name = '_user_tests.' + path.stem
+    spec = importlib.util.spec_from_file_location(name, path)
+    if spec is None or spec.loader is None:
+        raise click.ClickException(f'cannot import {path}')
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[name] = module
+    spec.loader.exec_module(module)
+    return module

sheetwright/config.py

@@ -0,0 +1,111 @@
+"""Read/write sheetwright.toml and workbook.toml."""
+
+from __future__ import annotations
+
+import dataclasses
+import tomllib
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+import tomli_w
+
+from sheetwright.exceptions import ProjectError
+from sheetwright.model.workbook import NamedRange
+from sheetwright.security import SecurityLimits
+
+
+@dataclass(frozen=True)
+class ProjectConfig:
+    name: str
+    calc_engine: str = 'libreoffice'
+    security: Optional[SecurityLimits] = None
+
+
+@dataclass
+class WorkbookManifest:
+    name: str
+    sheets: List[str] = field(default_factory=list)
+    named_ranges: List[NamedRange] = field(default_factory=list)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, WorkbookManifest):
+            return NotImplemented
+        return (
+            self.name == other.name
+            and self.sheets == other.sheets
+            and len(self.named_ranges) == len(other.named_ranges)
+            and all(
+                a.name == b.name
+                and a.scope == b.scope
+                and a.sheet == b.sheet
+                and a.ref == b.ref
+                for a, b in zip(self.named_ranges, other.named_ranges)
+            )
+        )
+
+
+def dump_project(cfg: ProjectConfig) -> str:
+    doc: Dict[str, Any] = {
+        'project': {'name': cfg.name},
+        'build': {'calc_engine': cfg.calc_engine},
+    }
+    if cfg.security is not None:
+        doc['security'] = dataclasses.asdict(cfg.security)
+    return tomli_w.dumps(doc)
+
+
+def load_project(text: str) -> ProjectConfig:
+    data = tomllib.loads(text)
+    security: Optional[SecurityLimits] = None
+    if 'security' in data:
+        sec = data['security']
+        defaults = SecurityLimits.defaults()
+        known = {f.name for f in dataclasses.fields(SecurityLimits)}
+        unknown = set(sec) - known
+        if unknown:
+            raise ProjectError(
+                f'Unknown [security] keys in sheetwright.toml: {sorted(unknown)}'
+            )
+        security = dataclasses.replace(defaults, **sec)
+    return ProjectConfig(
+        name=data['project']['name'],
+        calc_engine=data.get('build', {}).get('calc_engine', 'libreoffice'),
+        security=security,
+    )
+
+
+def dump_workbook(m: WorkbookManifest) -> str:
+    nrs = [
+        {
+            'name': nr.name,
+            'scope': nr.scope,
+            **({'sheet': nr.sheet} if nr.sheet else {}),
+            'ref': nr.ref,
+        }
+        for nr in m.named_ranges
+    ]
+    doc: Dict[str, Any] = {
+        'workbook': {'name': m.name, 'sheets': list(m.sheets)},
+    }
+    if nrs:
+        doc['named_ranges'] = nrs
+    return tomli_w.dumps(doc)
+
+
+def load_workbook(text: str) -> WorkbookManifest:
+    data = tomllib.loads(text)
+    nrs = [
+        NamedRange(
+            name=d['name'],
+            ref=d['ref'],
+            scope=d.get('scope', 'workbook'),
+            sheet=d.get('sheet'),
+        )
+        for d in data.get('named_ranges', [])
+    ]
+    wb = data['workbook']
+    return WorkbookManifest(
+        name=wb['name'],
+        sheets=list(wb.get('sheets', [])),
+        named_ranges=nrs,
+    )

sheetwright/diff/__init__.py

@@ -0,0 +1,23 @@
+"""Workbook diff: pure model + computation, no I/O."""
+
+from __future__ import annotations
+
+from sheetwright.diff.compute import diff_workbooks
+from sheetwright.diff.model import (
+    CellChange,
+    FrozenPanesChange,
+    NamedRangeChange,
+    PrintAreaChange,
+    SheetDiff,
+    WorkbookDiff,
+)
+
+__all__ = [
+    'CellChange',
+    'FrozenPanesChange',
+    'NamedRangeChange',
+    'PrintAreaChange',
+    'SheetDiff',
+    'WorkbookDiff',
+    'diff_workbooks',
+]