openstat-cli 1.0.0__py3-none-any.whl

openstat/config.py

@@ -0,0 +1,106 @@
+"""Configuration management for OpenStat.
+
+Loads settings from ~/.openstat/config.toml (if exists) with sensible defaults.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+_CONFIG_DIR = Path.home() / ".openstat"
+_CONFIG_FILE = _CONFIG_DIR / "config.toml"
+
+
+@dataclass
+class Config:
+    """OpenStat configuration with defaults."""
+
+    # Data
+    output_dir: str = "outputs"
+    csv_separator: str = ","
+    infer_schema_length: int = 10_000
+
+    # Display
+    tabulate_limit: int = 50
+    head_default: int = 10
+
+    # Undo
+    max_undo_stack: int = 20
+    max_undo_memory_mb: int = 500  # adaptive: skip snapshots if exceeds
+
+    # Plotting
+    plot_dpi: int = 150
+    plot_figsize_w: float = 8.0
+    plot_figsize_h: float = 5.0
+    plot_style: str = "default"
+
+    # Model
+    condition_threshold: int = 30
+    min_obs_per_predictor: int = 5
+    bootstrap_iterations: int = 1000
+
+    @classmethod
+    def load(cls) -> "Config":
+        """Load config from TOML file, falling back to defaults."""
+        cfg = cls()
+        if not _CONFIG_FILE.exists():
+            return cfg
+
+        try:
+            import tomllib
+        except ImportError:
+            try:
+                import tomli as tomllib  # type: ignore[no-redef]
+            except ImportError:
+                return cfg  # no TOML parser available, use defaults
+
+        try:
+            with open(_CONFIG_FILE, "rb") as f:
+                data = tomllib.load(f)
+        except Exception:
+            return cfg  # malformed config, use defaults
+
+        # Flatten sections
+        flat: dict[str, object] = {}
+        for section_key, section_val in data.items():
+            if isinstance(section_val, dict):
+                for k, v in section_val.items():
+                    flat[f"{section_key}_{k}"] = v
+            else:
+                flat[section_key] = section_val
+
+        # Apply known keys
+        for key in cfg.__dataclass_fields__:
+            if key in flat:
+                try:
+                    setattr(cfg, key, flat[key])
+                except (TypeError, ValueError):
+                    pass  # ignore invalid values
+
+        return cfg
+
+
+# Singleton — loaded once at import time
+_config: Config | None = None
+
+
+def get_config() -> Config:
+    """Return the global configuration (loads on first call)."""
+    global _config
+    if _config is None:
+        _config = Config.load()
+    return _config
+
+
+def reset_config(override: Config | None = None) -> Config:
+    """Reset the global config singleton.
+
+    If *override* is given it becomes the new config; otherwise
+    a fresh default ``Config()`` is used.  Returns the new config.
+
+    Intended for tests that need isolation from each other.
+    """
+    global _config
+    _config = override if override is not None else Config()
+    return _config

openstat/dsl/parser.py

@@ -0,0 +1,332 @@
+"""Safe recursive-descent parser: expression string -> Polars expression.
+
+Grammar:
+    expr     -> or_expr
+    or_expr  -> and_expr ('or' and_expr)*
+    and_expr -> not_expr ('and' not_expr)*
+    not_expr -> 'not' not_expr | compare
+    compare  -> add (comp_op add)?
+    add      -> mul (('+' | '-') mul)*
+    mul      -> power (('*' | '/' | '%') power)*
+    power    -> unary ('**' unary)?
+    unary    -> '-' unary | atom
+    atom     -> NUMBER | STRING | func_call | IDENT | '(' expr ')'
+    func_call -> IDENT '(' args? ')'
+    args     -> expr (',' expr)*
+
+Produces a polars.Expr.  No Python eval is ever used.
+
+Supported functions (whitelisted):
+    Math:    log, sqrt, abs, round, exp
+    String:  upper, lower, len_chars
+    Null:    is_null, is_not_null, fill_null
+    Type:    cast_float, cast_int, cast_str
+"""
+
+from __future__ import annotations
+
+import math
+
+import polars as pl
+
+from openstat.dsl.tokenizer import TT, Token, tokenize
+
+
+class ParseError(Exception):
+    pass
+
+
+# ── Whitelisted functions ────────────────────────────────────────────
+
+def _apply_function(name: str, args: list[pl.Expr]) -> pl.Expr:
+    """Apply a whitelisted function to Polars expressions."""
+    # Math functions (1 argument)
+    if name == "log" and len(args) == 1:
+        return args[0].log(math.e)
+    if name == "log10" and len(args) == 1:
+        return args[0].log(10)
+    if name == "sqrt" and len(args) == 1:
+        return args[0].sqrt()
+    if name == "abs" and len(args) == 1:
+        return args[0].abs()
+    if name == "exp" and len(args) == 1:
+        return args[0].exp()
+    if name == "round" and len(args) in (1, 2):
+        decimals = 0
+        if len(args) == 2:
+            # Extract literal integer from the expression
+            try:
+                # Evaluate the literal expression to get the integer value
+                decimals = int(pl.select(args[1]).item())
+            except Exception:
+                raise ParseError("round() second argument must be a literal integer")
+        return args[0].round(decimals)
+
+    # String functions (1 argument, operate on the column)
+    if name == "upper" and len(args) == 1:
+        return args[0].str.to_uppercase()
+    if name == "lower" and len(args) == 1:
+        return args[0].str.to_lowercase()
+    if name == "len_chars" and len(args) == 1:
+        return args[0].str.len_chars()
+    if name == "strip" and len(args) == 1:
+        return args[0].str.strip_chars()
+    if name == "contains" and len(args) == 2:
+        return args[0].str.contains(args[1])
+
+    # Null functions
+    if name == "is_null" and len(args) == 1:
+        return args[0].is_null()
+    if name == "is_not_null" and len(args) == 1:
+        return args[0].is_not_null()
+    if name == "fill_null" and len(args) == 2:
+        return args[0].fill_null(args[1])
+
+    # Cast functions
+    if name == "cast_float" and len(args) == 1:
+        return args[0].cast(pl.Float64)
+    if name == "cast_int" and len(args) == 1:
+        return args[0].cast(pl.Int64)
+    if name == "cast_str" and len(args) == 1:
+        return args[0].cast(pl.Utf8)
+
+    available = (
+        "log, log10, sqrt, abs, exp, round, "
+        "upper, lower, len_chars, strip, contains, "
+        "is_null, is_not_null, fill_null, "
+        "cast_float, cast_int, cast_str"
+    )
+    raise ParseError(
+        f"Unknown function '{name}' with {len(args)} argument(s). "
+        f"Available: {available}"
+    )
+
+
+# ── Parser ───────────────────────────────────────────────────────────
+
+class _Parser:
+    def __init__(self, tokens: list[Token]) -> None:
+        self.tokens = tokens
+        self.pos = 0
+
+    # -- helpers ---------------------------------------------------------
+
+    def _peek(self) -> Token:
+        return self.tokens[self.pos]
+
+    def _advance(self) -> Token:
+        tok = self.tokens[self.pos]
+        self.pos += 1
+        return tok
+
+    def _expect(self, tt: TT, value: str | None = None) -> Token:
+        tok = self._advance()
+        if tok.type != tt or (value is not None and tok.value != value):
+            raise ParseError(f"Expected {tt.name} {value!r}, got {tok}")
+        return tok
+
+    def _match_op(self, *ops: str) -> str | None:
+        tok = self._peek()
+        if tok.type == TT.OP and tok.value in ops:
+            self._advance()
+            return tok.value
+        return None
+
+    # -- grammar ---------------------------------------------------------
+
+    def parse(self) -> pl.Expr:
+        expr = self._or_expr()
+        if self._peek().type != TT.EOF:
+            raise ParseError(f"Unexpected token: {self._peek()}")
+        return expr
+
+    def _or_expr(self) -> pl.Expr:
+        left = self._and_expr()
+        while self._peek().type == TT.OR:
+            self._advance()
+            right = self._and_expr()
+            left = left | right
+        return left
+
+    def _and_expr(self) -> pl.Expr:
+        left = self._not_expr()
+        while self._peek().type == TT.AND:
+            self._advance()
+            right = self._not_expr()
+            left = left & right
+        return left
+
+    def _not_expr(self) -> pl.Expr:
+        if self._peek().type == TT.NOT:
+            self._advance()
+            return ~self._not_expr()
+        return self._compare()
+
+    def _compare(self) -> pl.Expr:
+        left = self._add()
+        op = self._match_op(">", "<", ">=", "<=", "==", "!=")
+        if op is None:
+            return left
+        right = self._add()
+        ops = {
+            ">": left > right,
+            "<": left < right,
+            ">=": left >= right,
+            "<=": left <= right,
+            "==": left == right,
+            "!=": left != right,
+        }
+        return ops[op]
+
+    def _add(self) -> pl.Expr:
+        left = self._mul()
+        while True:
+            op = self._match_op("+", "-")
+            if op is None:
+                break
+            right = self._mul()
+            left = left + right if op == "+" else left - right
+        return left
+
+    def _mul(self) -> pl.Expr:
+        left = self._power()
+        while True:
+            op = self._match_op("*", "/", "%")
+            if op is None:
+                break
+            right = self._power()
+            if op == "*":
+                left = left * right
+            elif op == "/":
+                left = left / right
+            else:
+                left = left % right
+        return left
+
+    def _power(self) -> pl.Expr:
+        base = self._unary()
+        if self._match_op("**"):
+            exp = self._unary()
+            return base.pow(exp)
+        return base
+
+    def _unary(self) -> pl.Expr:
+        if self._match_op("-"):
+            return -self._unary()
+        return self._atom()
+
+    def _atom(self) -> pl.Expr:
+        tok = self._peek()
+
+        if tok.type == TT.NUMBER:
+            self._advance()
+            val = float(tok.value) if "." in tok.value else int(tok.value)
+            return pl.lit(val)
+
+        if tok.type == TT.STRING:
+            self._advance()
+            return pl.lit(tok.value)
+
+        if tok.type == TT.IDENT:
+            # Check if it's a function call: IDENT '('
+            next_pos = self.pos + 1
+            if next_pos < len(self.tokens) and self.tokens[next_pos].type == TT.LPAREN:
+                return self._func_call()
+            self._advance()
+            return pl.col(tok.value)
+
+        if tok.type == TT.LPAREN:
+            self._advance()
+            expr = self._or_expr()
+            self._expect(TT.RPAREN)
+            return expr
+
+        raise ParseError(f"Unexpected token: {tok}")
+
+    def _func_call(self) -> pl.Expr:
+        """Parse function_name(arg1, arg2, ...)."""
+        name_tok = self._advance()  # IDENT
+        self._expect(TT.LPAREN)
+
+        args: list[pl.Expr] = []
+        if self._peek().type != TT.RPAREN:
+            args.append(self._or_expr())
+            while self._peek().type == TT.COMMA:
+                self._advance()  # skip comma
+                args.append(self._or_expr())
+
+        self._expect(TT.RPAREN)
+        return _apply_function(name_tok.value, args)
+
+
+def parse_expression(text: str) -> pl.Expr:
+    """Parse an expression string into a Polars Expr (safe, no eval)."""
+    tokens = tokenize(text)
+    return _Parser(tokens).parse()
+
+
+def parse_formula(text: str) -> tuple[str, list[str]]:
+    """Parse 'y ~ x1 + x2 + x3' into (dep_var, [indep_vars]).
+
+    The '+' here means 'include predictor', not arithmetic addition.
+
+    Interaction syntax:
+    - x1:x2  → interaction only (product term)
+    - x1*x2  → full factorial = x1 + x2 + x1:x2
+    """
+    text = text.strip()
+    if "~" not in text:
+        raise ParseError("Formula must contain '~', e.g. y ~ x1 + x2")
+    left, right = text.split("~", 1)
+    dep = left.strip()
+    if not dep:
+        raise ParseError("Missing dependent variable before '~'")
+
+    # Expand x1*x2 → x1 + x2 + x1:x2 before splitting on +
+    right = _expand_star_interactions(right)
+
+    indeps = [v.strip() for v in right.split("+")]
+    indeps = [v for v in indeps if v]
+    if not indeps:
+        raise ParseError("Missing independent variables after '~'")
+
+    # Normalize interaction terms: strip whitespace around ':'
+    indeps = [
+        ":".join(p.strip() for p in v.split(":")) if ":" in v else v
+        for v in indeps
+    ]
+
+    # Deduplicate while preserving order
+    seen: set[str] = set()
+    unique: list[str] = []
+    for v in indeps:
+        if v not in seen:
+            seen.add(v)
+            unique.append(v)
+
+    return dep, unique
+
+
+def _expand_star_interactions(rhs: str) -> str:
+    """Expand full-factorial ``*`` terms in a formula RHS string.
+
+    - ``x1*x2``       → ``x1 + x2 + x1:x2``
+    - ``x1*x2*x3``    → ``x1 + x2 + x3 + x1:x2 + x1:x3 + x2:x3 + x1:x2:x3``
+    """
+    from itertools import combinations
+
+    terms = [t.strip() for t in rhs.split("+")]
+    expanded: list[str] = []
+    for term in terms:
+        if "*" in term and ":" not in term:
+            parts = [p.strip() for p in term.split("*")]
+            # Generate all subsets of size 1..len(parts)
+            for r in range(1, len(parts) + 1):
+                for combo in combinations(parts, r):
+                    if r == 1:
+                        expanded.append(combo[0])
+                    else:
+                        expanded.append(":".join(combo))
+        else:
+            expanded.append(term)
+    return " + ".join(expanded)

openstat/dsl/tokenizer.py

@@ -0,0 +1,105 @@
+"""Safe tokenizer for OpenStat expressions.
+
+Produces a flat list of typed tokens from a string expression.
+No Python eval is ever used.
+
+Supports:
+- Backtick-quoted identifiers: `Column Name`, `income ($)`
+- Function calls: log(x), sqrt(x), is_null(x)
+- Standard operators and boolean keywords
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import Enum, auto
+
+
+class TT(Enum):
+    """Token types."""
+
+    NUMBER = auto()
+    STRING = auto()
+    IDENT = auto()
+    OP = auto()
+    LPAREN = auto()
+    RPAREN = auto()
+    COMMA = auto()
+    AND = auto()
+    OR = auto()
+    NOT = auto()
+    EOF = auto()
+
+
+@dataclass(frozen=True)
+class Token:
+    type: TT
+    value: str
+
+    def __repr__(self) -> str:
+        return f"Token({self.type.name}, {self.value!r})"
+
+
+# Order matters: longer operators first.
+_TOKEN_SPEC: list[tuple[TT | None, str]] = [
+    (None, r"\s+"),  # skip whitespace
+    (TT.NUMBER, r"\d+(?:\.\d+)?"),
+    (TT.STRING, r'"[^"]*"|\'[^\']*\''),
+    (TT.IDENT, r"`[^`]+`"),  # backtick-quoted identifiers
+    (TT.OP, r">=|<=|!=|==|>|<|\+|-|\*\*|\*|/|%"),
+    (TT.LPAREN, r"\("),
+    (TT.RPAREN, r"\)"),
+    (TT.COMMA, r","),
+    (TT.IDENT, r"[A-Za-z_][A-Za-z0-9_]*"),
+]
+
+_KEYWORDS = {"and": TT.AND, "or": TT.OR, "not": TT.NOT}
+
+_PATTERN = re.compile(
+    "|".join(f"(?P<G{i}>{pat})" for i, (_, pat) in enumerate(_TOKEN_SPEC))
+)
+
+
+def tokenize(text: str) -> list[Token]:
+    """Tokenize an expression string into a list of Tokens.
+
+    Raises ValueError if the input contains unrecognized characters.
+    """
+    tokens: list[Token] = []
+    last_end = 0
+    for m in _PATTERN.finditer(text):
+        # Check for unmatched characters between tokens
+        if m.start() > last_end:
+            bad = text[last_end:m.start()]
+            raise ValueError(
+                f"Unexpected character(s) at position {last_end}: {bad!r}"
+            )
+        last_end = m.end()
+        for i, (tt, _) in enumerate(_TOKEN_SPEC):
+            val = m.group(f"G{i}")
+            if val is not None:
+                if tt is None:
+                    break  # whitespace — skip
+                if tt == TT.IDENT:
+                    # Strip backticks if present
+                    if val.startswith("`") and val.endswith("`"):
+                        tokens.append(Token(TT.IDENT, val[1:-1]))
+                    elif val.lower() in _KEYWORDS:
+                        tokens.append(Token(_KEYWORDS[val.lower()], val.lower()))
+                    else:
+                        tokens.append(Token(tt, val))
+                elif tt == TT.STRING:
+                    tokens.append(Token(tt, val[1:-1]))  # strip quotes
+                else:
+                    tokens.append(Token(tt, val))
+                break
+    # Check for trailing unmatched characters
+    if last_end < len(text):
+        bad = text[last_end:]
+        if bad.strip():  # ignore trailing whitespace
+            raise ValueError(
+                f"Unexpected character(s) at position {last_end}: {bad.strip()!r}"
+            )
+    tokens.append(Token(TT.EOF, ""))
+    return tokens

openstat/i18n.py

@@ -0,0 +1,120 @@
+"""Lightweight i18n: translate UI strings for OpenStat.
+
+Usage::
+
+    from openstat.i18n import t, set_locale
+    set_locale("tr")
+    print(t("no_data"))  # → "Veri yüklenmedi."
+
+Supported locales: en (default), tr.
+Additional locales can be registered at runtime via ``register_locale()``.
+"""
+
+from __future__ import annotations
+
+_LOCALE: str = "en"
+
+_STRINGS: dict[str, dict[str, str]] = {
+    "en": {
+        # Generic errors
+        "no_data": "No dataset loaded. Use: load <path>",
+        "col_not_found": "Column not found: {col}",
+        "unknown_subcmd": "Unknown sub-command: {subcmd}",
+        # Data commands
+        "load_ok": "Loaded {rows:,} rows × {cols} columns from {path}",
+        "save_ok": "Saved to: {path}",
+        "describe_header": "Dataset: {name}  |  {rows:,} rows × {cols} columns",
+        "summarize_header": "Summary Statistics",
+        # Model results
+        "model_fitted": "{model} fitted. {info}",
+        "model_none": "No model fitted yet.",
+        # Export
+        "export_docx_ok": "Word document saved: {path}",
+        "export_pptx_ok": "PowerPoint saved: {path}",
+        # Session
+        "session_info_header": "Session Information",
+        "seed_set": "Seed set to {seed}. Reproducible random operations enabled.",
+        "seed_none": "No seed set.",
+        # Dashboard
+        "dashboard_closed": "Dashboard closed.",
+        "dashboard_missing": (
+            "textual is required for the dashboard.\n"
+            "Install: pip install textual"
+        ),
+        # Misc
+        "undo_ok": "Undo successful. Restored previous dataset.",
+        "undo_fail": "Nothing to undo.",
+    },
+    "tr": {
+        # Generic errors
+        "no_data": "Veri kümesi yüklenmedi. Kullanım: load <yol>",
+        "col_not_found": "Sütun bulunamadı: {col}",
+        "unknown_subcmd": "Bilinmeyen alt komut: {subcmd}",
+        # Data commands
+        "load_ok": "{path} dosyasından {rows:,} satır × {cols} sütun yüklendi",
+        "save_ok": "Kaydedildi: {path}",
+        "describe_header": "Veri kümesi: {name}  |  {rows:,} satır × {cols} sütun",
+        "summarize_header": "Özet İstatistikler",
+        # Model results
+        "model_fitted": "{model} tahmin edildi. {info}",
+        "model_none": "Henüz model tahmin edilmedi.",
+        # Export
+        "export_docx_ok": "Word belgesi kaydedildi: {path}",
+        "export_pptx_ok": "PowerPoint kaydedildi: {path}",
+        # Session
+        "session_info_header": "Oturum Bilgisi",
+        "seed_set": "Başlangıç değeri {seed} olarak ayarlandı. Tekrarlanabilir rastgele işlemler etkin.",
+        "seed_none": "Başlangıç değeri ayarlanmadı.",
+        # Dashboard
+        "dashboard_closed": "Gösterge paneli kapatıldı.",
+        "dashboard_missing": (
+            "Gösterge paneli için textual gereklidir.\n"
+            "Kurulum: pip install textual"
+        ),
+        # Misc
+        "undo_ok": "Geri alma başarılı. Önceki veri kümesi geri yüklendi.",
+        "undo_fail": "Geri alınacak bir şey yok.",
+    },
+}
+
+
+def set_locale(locale: str) -> None:
+    """Set the active locale (e.g. 'en', 'tr')."""
+    global _LOCALE
+    if locale not in _STRINGS:
+        raise ValueError(
+            f"Locale '{locale}' not available. "
+            f"Available: {', '.join(_STRINGS)}"
+        )
+    _LOCALE = locale
+
+
+def get_locale() -> str:
+    """Return the currently active locale code."""
+    return _LOCALE
+
+
+def register_locale(locale: str, strings: dict[str, str]) -> None:
+    """Register (or extend) a locale with a mapping of key → translated string.
+
+    Strings for keys not provided fall back to English.
+    """
+    if locale not in _STRINGS:
+        _STRINGS[locale] = {}
+    _STRINGS[locale].update(strings)
+
+
+def t(key: str, **kwargs: object) -> str:
+    """Translate *key* using the active locale, with optional format args.
+
+    Falls back to English if the key is missing in the active locale.
+    Returns the key itself if missing everywhere.
+    """
+    locale_map = _STRINGS.get(_LOCALE, {})
+    template = locale_map.get(key) or _STRINGS["en"].get(key) or key
+    if kwargs:
+        try:
+            return template.format(**kwargs)
+        except KeyError:
+            return template
+    return template