abax 0.1.2__py3-none-any.whl

abax/__init__.py

@@ -0,0 +1,4 @@
+"""abax — a keyboard-first statistics and data-science workstation."""
+
+__version__ = "0.1.2"
+__all__ = ["__version__"]

abax/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m abax`` entry point."""
+
+from .app import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

abax/_runtime.py

@@ -0,0 +1,119 @@
+"""Runtime detection: platform paths, optional-dependency booleans, version.
+
+Imported widely, so it stays cheap: no Qt, no curses, no heavy work at import.
+Mirrors the spec's _runtime.py exactly, parameterized for project "abax".
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+APP_NAME = "abax"
+
+# --- optional dependency flags --------------------------------------------
+
+try:
+    import msgspec as _ms  # noqa: F401
+
+    _HAS_MSGSPEC = True
+except ImportError:
+    _ms = None
+    _HAS_MSGSPEC = False
+
+try:
+    import platformdirs as _pd_mod  # noqa: F401
+
+    _HAS_PLATFORMDIRS = True
+except ImportError:
+    _pd_mod = None
+    _HAS_PLATFORMDIRS = False
+
+try:
+    import openpyxl as _openpyxl  # noqa: F401
+
+    _HAS_OPENPYXL = True
+except ImportError:
+    _openpyxl = None
+    _HAS_OPENPYXL = False
+
+try:
+    import importlib.util as _ilu
+
+    # GUI works on either Qt binding; PySide6 (LGPL) is preferred. Detect via
+    # find_spec so the fast paths never import a heavy Qt stack just to check.
+    _HAS_QT = (_ilu.find_spec("PySide6") is not None
+               or _ilu.find_spec("PyQt6") is not None)
+except Exception:
+    _HAS_QT = False
+
+try:
+    import textual  # noqa: F401
+
+    _HAS_TEXTUAL = True
+except ImportError:
+    _HAS_TEXTUAL = False
+
+# --- version flags ---------------------------------------------------------
+
+PY_VERSION = sys.version_info
+HAS_LAZY_IMPORTS = PY_VERSION >= (3, 15)  # PEP 810
+
+# --- platform paths --------------------------------------------------------
+
+if _HAS_PLATFORMDIRS:
+    from platformdirs import PlatformDirs as _PD
+
+    _dirs = _PD(APP_NAME, appauthor=False)
+    CONFIG_DIR = Path(_dirs.user_config_dir)
+    DATA_DIR = Path(_dirs.user_data_dir)
+    CACHE_DIR = Path(_dirs.user_cache_dir)
+    LOG_DIR = Path(_dirs.user_log_dir)
+else:
+    # stdlib fallback — mirrors platformdirs logic.
+    _home = Path.home()
+    if sys.platform == "win32":
+        _base = Path(os.environ.get("APPDATA", _home / "AppData/Roaming"))
+        _local = Path(os.environ.get("LOCALAPPDATA", _home / "AppData/Local"))
+        CONFIG_DIR = _base / APP_NAME
+        DATA_DIR = _local / APP_NAME
+        CACHE_DIR = _local / APP_NAME / "Cache"
+        LOG_DIR = _local / APP_NAME / "Logs"
+    elif sys.platform == "darwin":
+        _sup = _home / "Library" / "Application Support" / APP_NAME
+        CONFIG_DIR = _sup
+        DATA_DIR = _sup
+        CACHE_DIR = _home / "Library" / "Caches" / APP_NAME
+        LOG_DIR = _home / "Library" / "Logs" / APP_NAME
+    else:
+        _cfg = Path(os.environ.get("XDG_CONFIG_HOME", _home / ".config"))
+        _data = Path(os.environ.get("XDG_DATA_HOME", _home / ".local/share"))
+        _cache = Path(os.environ.get("XDG_CACHE_HOME", _home / ".cache"))
+        CONFIG_DIR = _cfg / APP_NAME
+        DATA_DIR = _data / APP_NAME
+        CACHE_DIR = _cache / APP_NAME
+        LOG_DIR = _data / APP_NAME / "logs"
+
+EXCHANGE_DIR = DATA_DIR / "exchange"
+
+for _d in (CONFIG_DIR, DATA_DIR, CACHE_DIR, LOG_DIR, EXCHANGE_DIR):
+    _d.mkdir(parents=True, exist_ok=True)
+
+# --- optional aggregate accelerator ---------------------------------------
+# The stdlib core reduces ranges itself; the engine layer may inject a faster
+# numpy-backed reducer here for large all-numeric ranges. core reads the slot
+# through this seam (abax._runtime is the one sanctioned cross-layer import),
+# so it never imports numpy directly.
+_aggregate_accelerator = None
+
+
+def set_aggregate_accelerator(fn) -> None:
+    """Register (or clear, with ``None``) the optional range-aggregate accelerator."""
+    global _aggregate_accelerator
+    _aggregate_accelerator = fn
+
+
+def aggregate_accelerator():
+    """The currently registered aggregate accelerator, or ``None``."""
+    return _aggregate_accelerator

abax/app.py

@@ -0,0 +1,239 @@
+"""CLI entry point.
+
+Lazy imports only — never import Qt, Textual, or curses at module top level.
+The ``--help``/``--version``/``--deps`` fast paths respond instantly without
+touching the GUI/TUI stacks (and never create a venv).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="abax",
+        description="abax — a keyboard-first statistics and data-science workstation.",
+    )
+    p.add_argument("--version", action="store_true", help="print version and exit")
+    p.add_argument("--deps", action="store_true", help="print optional-dependency status and exit")
+    p.add_argument(
+        "--macros",
+        action="append",
+        default=[],
+        metavar="PATH",
+        help="macro file or directory to load (repeatable); adds UDFs and macros",
+    )
+    sub = p.add_subparsers(dest="command")
+
+    pg = sub.add_parser("gui", help="launch the Qt GUI")
+    pg.add_argument("file", nargs="?", help="spreadsheet to open")
+
+    pt = sub.add_parser("tui", help="launch the curses TUI")
+    pt.add_argument("file", nargs="?", help="spreadsheet to open")
+
+    pv = sub.add_parser("view", help="print a spreadsheet as a table")
+    pv.add_argument("file", help="spreadsheet to open (.csv/.xlsx/.json)")
+    pv.add_argument("--sheet", help="sheet name (default: active)")
+
+    pc = sub.add_parser("convert", help="convert between formats by extension")
+    pc.add_argument("src")
+    pc.add_argument("dst")
+    pc.add_argument("--values", action="store_true", help="write computed values, not formulas")
+
+    pe = sub.add_parser("get", help="print one cell's computed value")
+    pe.add_argument("file")
+    pe.add_argument("ref", help="A1 reference, e.g. B7")
+
+    sub.add_parser("deps", help="install the optional dependencies (full-fat)")
+
+    pm = sub.add_parser("macro", help="list or run macros")
+    msub = pm.add_subparsers(dest="macro_cmd")
+    msub.add_parser("list", help="list discovered macros and user functions")
+    mr = msub.add_parser("run", help="run a macro against a file")
+    mr.add_argument("name")
+    mr.add_argument("file")
+    mr.add_argument("-o", "--output", help="save path (default: overwrite the input file)")
+    mr.add_argument("--at", metavar="A1", help="anchor cell for relative macros (e.g. C5)")
+
+    return p
+
+
+_SUBCOMMANDS = frozenset({"gui", "tui", "view", "convert", "get", "macro", "deps"})
+
+
+def _normalize_argv(argv: list[str]) -> list[str]:
+    """A bare file path (no subcommand) opens it in the GUI, so `abax data.csv`
+    behaves like `abax gui data.csv`. Flags and real subcommands pass through."""
+    if argv and not argv[0].startswith("-") and argv[0] not in _SUBCOMMANDS:
+        return ["gui", *argv]
+    return argv
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = _normalize_argv(sys.argv[1:] if argv is None else argv)
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    # --- fast paths (no heavy imports) ---
+    if args.version:
+        print(f"abax {__version__}")
+        return 0
+    if args.deps:
+        from .diagnostics import format_deps
+
+        print(format_deps())
+        return 0
+
+    # Load macros (and their UDFs) so every command — view/get/gui/tui — can use
+    # them. Cheap when no macro files exist; runs after the fast paths above.
+    from .macros import default_macro_dirs, discover_macros, install_functions
+
+    registry = discover_macros([*default_macro_dirs(), *args.macros])
+    udfs = install_functions(registry)
+
+    cmd = args.command
+    if cmd == "gui":
+        from .gui.runner import run_gui
+
+        return run_gui(args.file, registry)
+    if cmd == "tui":
+        from .tui import run_tui
+
+        return run_tui(args.file, registry)
+    if cmd == "view":
+        return _cmd_view(args.file, args.sheet)
+    if cmd == "convert":
+        return _cmd_convert(args.src, args.dst, args.values)
+    if cmd == "get":
+        return _cmd_get(args.file, args.ref)
+    if cmd == "deps":
+        return _cmd_deps()
+    if cmd == "macro":
+        return _cmd_macro(args, registry, udfs)
+
+    # No subcommand: prefer GUI, fall back to TUI, then help.
+    from . import _runtime as rt
+
+    if rt._HAS_QT:
+        from .gui.runner import run_gui
+
+        return run_gui(None, registry)
+    if sys.stdout.isatty():
+        from .tui import run_tui
+
+        return run_tui(None, registry)
+    parser.print_help()
+    return 0
+
+
+def _cmd_deps() -> int:
+    """Install every optional dependency (full-fat), blocking with progress."""
+    from . import autodeps
+
+    autodeps.set_enabled(True)
+    todo = autodeps.prefetch_all(background=False, force=True)
+    if todo:
+        print(f"Attempted {len(todo)} package(s): {', '.join(todo)}")
+    have = sum(1 for _pip, mod in autodeps.ALL if autodeps.installed(mod))
+    print(f"Optional dependencies present: {have}/{len(autodeps.ALL)}")
+    return 0
+
+
+def _cmd_view(path: str, sheet_name: str | None) -> int:
+    from .engine.document import Document
+
+    doc = Document.open(path)
+    sheet = doc.workbook.get_sheet(sheet_name) if sheet_name else doc.workbook.sheet
+    if sheet is None:
+        print(f"no such sheet: {sheet_name}", file=sys.stderr)
+        return 2
+    print(_render_table(sheet))
+    return 0
+
+
+def _cmd_convert(src: str, dst: str, values: bool) -> int:
+    from .engine.document import Document
+
+    doc = Document.open(src)
+    try:
+        doc.save(dst)
+    except RuntimeError as exc:  # e.g. openpyxl missing
+        print(str(exc), file=sys.stderr)
+        return 3
+    print(f"converted {src} -> {dst}")
+    return 0
+
+
+def _cmd_get(path: str, ref: str) -> int:
+    from .engine.document import Document
+
+    doc = Document.open(path)
+    print(doc.workbook.sheet.format_value(doc.workbook.sheet.get(ref)))
+    return 0
+
+
+def _cmd_macro(args, registry, udfs) -> int:
+    if args.macro_cmd == "run":
+        from .engine.document import Document
+        from .macros import MacroError, run_macro
+
+        cursor = None
+        if args.at:
+            from .core.reference import parse_a1
+
+            cursor = parse_a1(args.at)
+        doc = Document.open(args.file)
+        try:
+            ctx = run_macro(registry, args.name, doc.workbook, cursor=cursor)
+        except MacroError as exc:
+            print(str(exc), file=sys.stderr)
+            return 4
+        for msg in ctx.messages:
+            print(msg)
+        out = args.output or args.file
+        doc.save(out)
+        print(f"ran macro {args.name!r}; saved {out}")
+        return 0
+
+    # default / "list"
+    if registry.macros:
+        print("macros:")
+        for name in sorted(registry.macros):
+            print(f"  {name}")
+    else:
+        print("no macros found (drop .py files in CONFIG_DIR/macros or pass --macros PATH)")
+    if udfs:
+        print("user functions:")
+        for name in udfs:
+            print(f"  {name}()")
+    return 0
+
+
+def _render_table(sheet) -> str:
+    from .core.reference import index_to_col
+
+    n_rows, n_cols = sheet.used_bounds()
+    if n_rows == 0:
+        return "(empty)"
+    cells = [[sheet.display(r, c) for c in range(n_cols)] for r in range(n_rows)]
+    headers = [index_to_col(c) for c in range(n_cols)]
+    row_label_w = len(str(n_rows))
+    widths = [
+        max(len(headers[c]), max((len(cells[r][c]) for r in range(n_rows)), default=0))
+        for c in range(n_cols)
+    ]
+    out = [" " * row_label_w + " | " + " | ".join(h.ljust(widths[c]) for c, h in enumerate(headers))]
+    out.append("-" * len(out[0]))
+    for r in range(n_rows):
+        line = str(r + 1).rjust(row_label_w) + " | "
+        line += " | ".join(cells[r][c].ljust(widths[c]) for c in range(n_cols))
+        out.append(line)
+    return "\n".join(out)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

abax/autodeps.py

@@ -0,0 +1,221 @@
+"""On-demand auto-installation of abax's optional dependencies.
+
+abax's core is stdlib-only and every heavier capability is an *optional* package
+with a graceful fallback. By default abax fetches those packages **automatically**
+in the background, so a plain install grows into a "full-fat" one on its own — the
+data-science stack, Excel/Parquet I/O, the PTY terminal, and Jupyter integration
+all appear without the user running a single `pip install … [extra]`.
+
+Design points:
+- **Best-effort & non-blocking.** Installs run in a daemon thread; startup and the
+  UI never wait on pip. If pip is missing, the machine is offline, or a build fails,
+  abax silently keeps using its pure-Python fallbacks.
+- **Attempted once per machine.** A marker file per package (under the cache dir)
+  means a slow or failing install isn't retried on every launch. A *forced* install
+  (the explicit "install optional features now" action) ignores the markers.
+- **Opt-out.** ``settings.auto_install = False`` or the ``ABAX_NO_AUTOINSTALL``
+  environment variable disables it entirely.
+
+The GUI binding itself (PySide6/PyQt6) is **not** auto-installed — you need a Qt
+binding to launch the GUI in the first place, and it's the one heavyweight a user
+deliberately chooses (`pip install abax[gui]`).
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import subprocess
+import sys
+import threading
+
+# (pip distribution name, import module name) for every optional dependency.
+# Ordered light -> heavy so the quick wins land first and the slowest (pymc) last.
+_SCIENCE = [
+    ("numpy", "numpy"), ("pandas", "pandas"), ("scipy", "scipy"),
+    ("scikit-learn", "sklearn"), ("statsmodels", "statsmodels"),
+    ("pingouin", "pingouin"), ("lifelines", "lifelines"),
+    ("scikit-survival", "sksurv"),
+]
+# Bayesian stack, split out (pymc pulls pytensor + arviz + numba/llvmlite ~150 MB).
+# Still part of the default full-fat `ALL` set below.
+_BAYES = [("pymc", "pymc")]
+_TERMINAL = [("pyte", "pyte")]
+if sys.platform == "win32":
+    _TERMINAL.append(("pywinpty", "winpty"))   # ConPTY backend on Windows
+
+FEATURES: dict[str, list[tuple[str, str]]] = {
+    "fast-io": [("platformdirs", "platformdirs"), ("msgspec", "msgspec")],
+    "excel": [("openpyxl", "openpyxl")],
+    "parquet": [("pyarrow", "pyarrow")],
+    "terminal": _TERMINAL,
+    "tui": [("rich", "rich"), ("textual", "textual")],
+    "jupyter": [("nbformat", "nbformat"), ("ipykernel", "ipykernel"),
+                ("anywidget", "anywidget")],
+    "science": _SCIENCE,
+    "bayes": _BAYES,
+}
+
+# The full-fat set (the `all` extra), ordered light -> heavy so the quick wins
+# land first and the heaviest (pymc) last; markers dedupe across features.
+ALL: list[tuple[str, str]] = [
+    ("platformdirs", "platformdirs"), ("msgspec", "msgspec"),
+    ("openpyxl", "openpyxl"),
+    *_TERMINAL,
+    ("rich", "rich"), ("textual", "textual"),
+    ("nbformat", "nbformat"), ("anywidget", "anywidget"),
+    ("pyarrow", "pyarrow"),
+    *_SCIENCE,
+    ("ipykernel", "ipykernel"),
+    *_BAYES,
+]
+
+# Human-facing descriptions for the first-run chooser: feature -> (label,
+# what it installs, approximate MB). Feature closures share dependencies, so the
+# totals for a preset are smaller than the sum of the parts.
+FEATURE_INFO: dict[str, tuple[str, str, int]] = {
+    "fast-io": ("Faster settings & correct folders",
+                "msgspec + platformdirs", 8),
+    "excel": ("Excel spreadsheets (.xlsx)", "openpyxl", 4),
+    "terminal": ("A true terminal panel",
+                 "pyte" + (" + pywinpty" if sys.platform == "win32" else ""), 3),
+    "tui": ("A richer terminal UI", "textual + rich", 12),
+    "jupyter": ("Jupyter integration",
+                "nbformat + ipykernel + anywidget — notebook validation, the abax "
+                "kernel, and the editable-sheet widget", 80),
+    "parquet": ("Parquet / Feather data files", "pyarrow", 90),
+    "science": ("Data science: statistics, ML, DataFrames, graphing",
+                "numpy, pandas, scipy, scikit-learn, statsmodels, lifelines, "
+                "pingouin, scikit-survival", 450),
+    "bayes": ("Bayesian / probabilistic modeling (large)",
+              "pymc + pytensor + arviz + numba/llvmlite", 150),
+}
+
+# The two common presets offered by the chooser. "thin" = the lean conveniences
+# (matching the pip `thin` extra minus the Qt binding); "all" = everything.
+PRESETS: dict[str, list[str]] = {
+    "thin": ["fast-io", "excel", "terminal", "tui"],
+    "all": list(FEATURES),
+}
+
+
+def preset(name: str) -> list[str]:
+    """Feature keys for a named preset (``"thin"`` / ``"all"``)."""
+    return list(PRESETS.get(name, []))
+
+
+# --- configuration / hooks (the install fn + marker dir are injectable for tests)
+_INSTALL_FN = None          # set below; tests may replace it
+_MARKER_DIR = None          # None -> CACHE_DIR/autodeps
+_enabled_override: bool | None = None
+_lock = threading.Lock()
+_attempted_session: set[str] = set()
+
+
+def set_enabled(flag: bool | None) -> None:
+    """Force auto-install on/off (``None`` restores the default)."""
+    global _enabled_override
+    _enabled_override = flag
+
+
+def enabled() -> bool:
+    if os.environ.get("ABAX_NO_AUTOINSTALL"):
+        return False
+    if _enabled_override is not None:
+        return _enabled_override
+    return True
+
+
+def installed(import_name: str) -> bool:
+    try:
+        return importlib.util.find_spec(import_name) is not None
+    except Exception:
+        return False
+
+
+def _marker_dir():
+    from pathlib import Path
+    if _MARKER_DIR is not None:
+        return Path(_MARKER_DIR)
+    from ._runtime import CACHE_DIR
+    return CACHE_DIR / "autodeps"
+
+
+def _attempted(pip_name: str) -> bool:
+    if pip_name in _attempted_session:
+        return True
+    try:
+        return (_marker_dir() / f"{pip_name}.attempted").exists()
+    except Exception:
+        return False
+
+
+def _mark(pip_name: str) -> None:
+    _attempted_session.add(pip_name)
+    try:
+        d = _marker_dir()
+        d.mkdir(parents=True, exist_ok=True)
+        (d / f"{pip_name}.attempted").write_text("1", encoding="utf-8")
+    except Exception:
+        pass
+
+
+def _pip_install(pip_name: str, timeout: float = 1800) -> bool:
+    try:
+        proc = subprocess.run(
+            [sys.executable, "-m", "pip", "install", "--quiet", pip_name],
+            capture_output=True, timeout=timeout)
+        return proc.returncode == 0
+    except Exception:
+        return False
+
+
+_INSTALL_FN = _pip_install
+
+
+def missing(packages) -> list[tuple[str, str]]:
+    """The subset of ``(pip, module)`` pairs whose module isn't importable."""
+    return [(pip, mod) for pip, mod in packages if not installed(mod)]
+
+
+def ensure(packages, *, background: bool = True, force: bool = False) -> list[str]:
+    """Install any missing packages, best-effort and once.
+
+    ``packages`` is a list of ``(pip_name, import_name)`` pairs. Returns the pip
+    names it will attempt (empty if disabled, all present, or already attempted).
+    With ``force`` it ignores the once-per-machine markers (still skips packages
+    already importable).
+    """
+    if not enabled():
+        return []
+    todo: list[str] = []
+    with _lock:
+        for pip, mod in packages:
+            if installed(mod):
+                continue
+            if not force and _attempted(pip):
+                continue
+            _mark(pip)                     # claim now so concurrent calls don't race
+            todo.append(pip)
+    if not todo:
+        return []
+
+    def work() -> None:
+        for pip in todo:
+            _INSTALL_FN(pip)
+
+    if background:
+        threading.Thread(target=work, name="abax-autodeps", daemon=True).start()
+    else:
+        work()
+    return todo
+
+
+def ensure_feature(key: str, *, background: bool = True, force: bool = False) -> list[str]:
+    """Ensure the packages backing one feature (e.g. ``"science"``/``"excel"``)."""
+    return ensure(FEATURES.get(key, []), background=background, force=force)
+
+
+def prefetch_all(*, background: bool = True, force: bool = False) -> list[str]:
+    """Fetch the entire full-fat optional stack (called once on GUI startup)."""
+    return ensure(ALL, background=background, force=force)