augplot 0.1.0__py3-none-any.whl

augplot/exporting.py

@@ -0,0 +1,105 @@
+"""Write self-contained functions while preserving user-authored definitions."""
+
+import ast
+import keyword
+import os
+import symtable
+import tempfile
+from pathlib import Path
+
+_GENERATED_MARKER = "# Generated by Augplot. Review before running on new data."
+
+
+def write_python_function(
+    code: str, path: str | Path, function_name: str, *, backend="auto"
+) -> Path:
+    if (
+        not function_name.isidentifier()
+        or keyword.iskeyword(function_name)
+        or function_name.startswith("_")
+    ):
+        raise ValueError("function_name must be a public Python identifier.")
+    target = Path(path)
+    if target.suffix != ".py":
+        raise ValueError("Python output path must end in .py.")
+    if target.is_symlink():
+        raise ValueError("Refusing to replace a symlink; use a regular Python file.")
+    existing = target.read_text(encoding="utf-8") if target.exists() else ""
+    try:
+        existing_tree = ast.parse(existing)
+        symbols = symtable.symtable(existing, str(target), "exec")
+    except SyntaxError:
+        raise ValueError(
+            "Existing Python module is not valid Python; it was not changed."
+        ) from None
+    replacement = None
+    if function_name in symbols.get_identifiers():
+        for node in existing_tree.body:
+            is_matching_function = isinstance(
+                node, (ast.FunctionDef, ast.AsyncFunctionDef)
+            ) and node.name == function_name
+            if is_matching_function:
+                marker_index = node.lineno - 2
+                lines = existing.splitlines(keepends=True)
+                if marker_index >= 0 and lines[marker_index].rstrip("\r\n") == _GENERATED_MARKER:
+                    replacement = (marker_index, node.end_lineno)
+                break
+        if replacement is None:
+            raise ValueError(
+                f"Name {function_name!r} already exists and was not generated by Augplot; "
+                "choose a different function_name."
+            )
+    tree = ast.parse(code)
+    tree.body[0].name = function_name
+    # Reproduce the runtime style contexts in standalone source, without Augplot.
+    preamble = "import matplotlib as augplot_mpl\n"
+    context = "augplot_mpl.rc_context()"
+    if backend in ("auto", "seaborn"):
+        preamble += "import seaborn as augplot_sns\n"
+        context += (
+            ", augplot_sns.axes_style('whitegrid'), augplot_sns.plotting_context('notebook')"
+        )
+    wrapper = ast.parse(preamble + f"with {context}:\n    pass\n").body
+    wrapper[-1].body = tree.body[0].body
+    tree.body[0].body = wrapper
+    ast.fix_missing_locations(tree)
+    source = ast.unparse(tree) + "\n"
+    generated = _GENERATED_MARKER + "\n" + source
+    if replacement is None:
+        content = existing.rstrip() + "\n\n\n" if existing.strip() else ""
+        content += generated
+    else:
+        lines = existing.splitlines(keepends=True)
+        start, end = replacement
+        content = "".join(lines[:start]) + generated + "".join(lines[end:])
+    # Verify the entire module before touching the destination.
+    compile(content, str(target), "exec")
+    temporary = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            dir=target.parent,
+            prefix=".augplot-",
+            suffix=".tmp",
+            delete=False,
+        ) as handle:
+            temporary = Path(handle.name)
+            handle.write(content)
+            handle.flush()
+            os.fsync(handle.fileno())
+        if target.exists():
+            temporary.chmod(target.stat().st_mode & 0o777)
+        os.replace(temporary, target)
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+    if target.stem.isidentifier() and not keyword.iskeyword(target.stem):
+        print(
+            f"# With {str(target.parent)!r} on your Python import path:\n"
+            f"from {target.stem} import {function_name}\n"
+            f"fig = {function_name}(your_data)\nfig"
+        )
+    else:
+        print(f"Saved {function_name} to {target}. Use a valid module filename for direct imports.")
+    return target

augplot/history.py

@@ -0,0 +1,193 @@
+"""Persistent, versioned source history. Never deserialize executable Python objects."""
+
+import datetime as dt
+import hashlib
+import json
+import os
+import struct
+import tempfile
+import uuid
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from .errors import ConfigurationError, DataError
+from .execution import API_MANIFEST_VERSION
+
+HISTORY_VERSION = 1
+
+
+def fingerprint(data):
+    """Hash all values, ordering, and plotting-relevant schema, not a sampled profile."""
+    digest = hashlib.sha256()
+
+    def token(value):
+        payload = value if isinstance(value, bytes) else str(value).encode("utf-8")
+        digest.update(len(payload).to_bytes(8, "big"))
+        digest.update(payload)
+
+    def dtype(value):
+        token(str(value))
+        if isinstance(value, pd.CategoricalDtype):
+            visit(value.categories)
+            visit(value.ordered)
+
+    def visit(value):
+        token(f"{type(value).__module__}.{type(value).__qualname__}")
+        if value is None or value is pd.NA or value is pd.NaT:
+            return
+        if isinstance(value, pd.DataFrame):
+            visit(value.index)
+            visit(value.columns)
+            for i in range(len(value.columns)):
+                visit(value.iloc[:, i])
+        elif isinstance(value, (pd.Series, pd.Index)):
+            if isinstance(value, pd.Series):
+                visit(value.index)
+                visit(value.name)
+            else:
+                visit(list(value.names))
+                token(str(getattr(value, "freqstr", None)))
+                if isinstance(value, pd.MultiIndex):
+                    for level in value.levels:
+                        visit(level)
+            dtype(value.dtype)
+            token(len(value))
+            for item in value:
+                visit(item)
+        elif isinstance(value, np.ndarray):
+            token(value.dtype.str)
+            token(repr(value.dtype.descr))
+            visit(value.shape)
+            if value.dtype.hasobject:
+                for item in value.flat:
+                    visit(item)
+            else:
+                token(value.tobytes(order="C"))
+        elif isinstance(value, np.generic):
+            token(value.dtype.str)
+            token(repr(value.dtype.descr))
+            if value.dtype.hasobject:
+                visit(value.tolist())
+            else:
+                token(value.tobytes())
+        elif isinstance(value, dict):
+            token(len(value))
+            for key, item in value.items():
+                visit(key)
+                visit(item)
+        elif isinstance(value, (tuple, list)):
+            token(len(value))
+            for item in value:
+                visit(item)
+        elif isinstance(value, (str, bool, int)):
+            token(value)
+        elif isinstance(value, float):
+            token(struct.pack("!d", value))
+        elif isinstance(value, complex):
+            token(struct.pack("!dd", value.real, value.imag))
+        elif isinstance(value, pd.Period):
+            token(value.ordinal)
+            token(value.freqstr)
+        elif isinstance(value, pd.Interval):
+            visit(value.left)
+            visit(value.right)
+            token(value.closed)
+        elif isinstance(value, dt.date):
+            token(value.isoformat())
+            token(getattr(value, "fold", 0))
+            token(str(getattr(value, "tzinfo", None)))
+        elif isinstance(value, dt.timedelta):
+            token(str(value))
+        else:
+            raise DataError("Cannot fingerprint this input; convert it to ordinary data first.")
+
+    visit(data)
+    return digest.hexdigest()
+
+
+def request_key(settings):
+    payload = json.dumps(settings, sort_keys=True, ensure_ascii=True, allow_nan=False)
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+class History:
+    def __init__(self, directory):
+        self.directory = Path(directory).expanduser().resolve()
+
+    def load(self, root, key):
+        entry = self.directory / root / f"{key}.json"
+        if not entry.exists():
+            return None
+        try:
+            record = json.loads(entry.read_text(encoding="utf-8"))
+            if (
+                record["history_version"] != HISTORY_VERSION
+                or record["api_manifest_version"] != API_MANIFEST_VERSION
+                or record["request_key"] != key
+                or record["root"] != root
+                or not isinstance(record["explanation"], str)
+                or not isinstance(record["depth"], int)
+                or record["depth"] < 0
+                or not isinstance(record["revision"], str)
+            ):
+                raise ValueError("Invalid history record")
+            filename = record["filename"]
+            if not isinstance(filename, str) or Path(filename).name != filename:
+                raise ValueError("Invalid source path")
+            source = entry.parent / filename
+            code = source.read_text(encoding="utf-8")
+            if hashlib.sha256(code.encode("utf-8")).hexdigest() != record["code_hash"]:
+                raise ValueError("Source checksum mismatch")
+            return record, code, source
+        except (OSError, ValueError, KeyError, TypeError):
+            raise ConfigurationError(
+                "Saved visualization history is unreadable or changed. Restore it or "
+                "pass regenerate=True to explicitly generate a new version."
+            ) from None
+
+    def save(self, root, key, *, code, explanation, depth, parent, data_fingerprint):
+        directory = self.directory / root
+        revision = uuid.uuid4().hex
+        label = "initial" if depth == 0 else f"refined_{depth}"
+        filename = f"{label}_{revision}.py"
+        record = {
+            "history_version": HISTORY_VERSION,
+            "api_manifest_version": API_MANIFEST_VERSION,
+            "root": root,
+            "request_key": key,
+            "revision": revision,
+            "parent": parent,
+            "data_fingerprint": data_fingerprint,
+            "depth": depth,
+            "filename": filename,
+            "code_hash": hashlib.sha256(code.encode("utf-8")).hexdigest(),
+            "explanation": explanation,
+        }
+        temporary = None
+        try:
+            directory.mkdir(parents=True, exist_ok=True)
+            source = directory / filename
+            # Immutable source and metadata preserve earlier explicitly regenerated versions.
+            source.write_text(code, encoding="utf-8")
+            serialized = json.dumps(record, indent=2) + "\n"
+            (directory / f"{label}_{revision}.json").write_text(serialized, encoding="utf-8")
+            with tempfile.NamedTemporaryFile(
+                mode="w", encoding="utf-8", dir=directory, delete=False
+            ) as handle:
+                temporary = Path(handle.name)
+                handle.write(serialized)
+                handle.flush()
+                os.fsync(handle.fileno())
+            # Publish the lookup only after the complete source has been written.
+            os.replace(temporary, directory / f"{key}.json")
+        except OSError:
+            raise ConfigurationError(
+                "Could not save visualization history. Choose a writable cache_dir "
+                "or use cache_dir=None to disable persistence."
+            ) from None
+        finally:
+            if temporary is not None:
+                temporary.unlink(missing_ok=True)
+        return record, code, source

augplot/profiling.py

@@ -0,0 +1,273 @@
+"""Bounded, JSON-safe profiles of ordinary in-memory data science objects."""
+
+import copy
+import datetime as dt
+import json
+import math
+from itertools import islice
+
+import numpy as np
+import pandas as pd
+
+from .errors import DataError
+
+_SCALARS = (str, bool, int, float, dt.date, dt.timedelta, np.generic)
+
+
+def validate_data(data):
+    """Reject cycles/custom objects before copying or inspecting their representations."""
+    if not isinstance(data, (dict, list, tuple, np.ndarray, pd.DataFrame, pd.Series)):
+        raise DataError("Expected a dictionary, record list, NumPy array, DataFrame, or Series.")
+    if isinstance(data, np.ndarray) and data.ndim not in (1, 2):
+        raise DataError("Only one- and two-dimensional NumPy arrays are supported.")
+    if len(data) == 0 or isinstance(data, pd.DataFrame) and data.empty:
+        raise DataError("Cannot visualize empty data.")
+
+    def visit(value, ancestors, depth):
+        if depth > 32:
+            raise DataError("Input nesting exceeds 32 levels.")
+        if value is None or value is pd.NA or value is pd.NaT:
+            return
+        if isinstance(value, _SCALARS):
+            return
+        identity = id(value)
+        if identity in ancestors:
+            raise DataError("Cyclic input containers are not supported.")
+        chain = ancestors | {identity}
+        if isinstance(value, pd.DataFrame):
+            for column in value.columns:
+                visit(column, chain, depth + 1)
+            visit(value.index.tolist(), chain, depth + 1)
+            for index in range(len(value.columns)):
+                visit(value.iloc[:, index], chain, depth + 1)
+        elif isinstance(value, pd.Series):
+            visit(value.name, chain, depth + 1)
+            visit(value.index.tolist(), chain, depth + 1)
+            if value.dtype == object or isinstance(value.dtype, pd.CategoricalDtype):
+                for item in value:
+                    visit(item, chain, depth + 1)
+        elif isinstance(value, np.ndarray):
+            if value.ndim not in (1, 2):
+                raise DataError("Only one- and two-dimensional NumPy arrays are supported.")
+            if value.dtype.hasobject:
+                for item in value.flat:
+                    visit(item, chain, depth + 1)
+        elif isinstance(value, dict):
+            for key, item in value.items():
+                if not isinstance(key, (str, int, float, bool, tuple, np.generic)):
+                    raise DataError("Dictionary keys must be scalar values or tuples.")
+                visit(key, chain, depth + 1)
+                visit(item, chain, depth + 1)
+        elif isinstance(value, (list, tuple)):
+            for item in value:
+                visit(item, chain, depth + 1)
+        else:
+            raise DataError(
+                "Input contains an unsupported object; convert it to ordinary data first."
+            )
+
+    visit(data, set(), 0)
+
+
+def copy_data(data):
+    """Copy nested values too: Pandas' deep copy leaves object-dtype cells shared."""
+    if isinstance(data, pd.DataFrame):
+        result = data.copy(deep=True)
+        for index in range(len(data.columns)):
+            column = data.iloc[:, index]
+            if column.dtype == object:
+                result.isetitem(index, column.map(copy_data))
+        return result
+    if isinstance(data, pd.Series):
+        result = data.copy(deep=True)
+        if data.dtype == object:
+            for index in range(len(data)):
+                result.iloc[index] = copy_data(data.iloc[index])
+        return result
+    if isinstance(data, dict):
+        return {key: copy_data(value) for key, value in data.items()}
+    if isinstance(data, list):
+        return [copy_data(value) for value in data]
+    if isinstance(data, tuple):
+        return tuple(copy_data(value) for value in data)
+    if isinstance(data, np.ndarray) and data.dtype.hasobject:
+        result = data.copy()
+        for index in range(data.size):
+            result.flat[index] = copy_data(data.flat[index])
+        return result
+    return copy.deepcopy(data)
+
+
+def _indices(length, count):
+    return np.linspace(0, length - 1, min(length, count), dtype=int).tolist() if length else []
+
+
+def _value(value, depth=0):
+    if value is None or value is pd.NA or value is pd.NaT:
+        return None
+    if isinstance(value, np.generic):
+        if isinstance(value, (np.datetime64, np.timedelta64)):
+            return str(value)
+        if isinstance(value, np.floating):
+            return _value(float(value), depth)
+        return _value(value.item(), depth)
+    if isinstance(value, float):
+        return value if math.isfinite(value) else None
+    if isinstance(value, (bool, int)):
+        return value
+    if isinstance(value, str):
+        return value if len(value) <= 200 else value[:200] + "…[truncated]"
+    if isinstance(value, (dt.date, dt.timedelta)):
+        return str(value)
+    if depth >= 4:
+        return {"type": type(value).__name__, "truncated": True}
+    if isinstance(value, dict):
+        return {
+            "items": [
+                [_value(k, depth + 1), _value(v, depth + 1)] for k, v in islice(value.items(), 5)
+            ],
+            "length": len(value),
+        }
+    if isinstance(value, (list, tuple, np.ndarray)):
+        return [_value(value[i], depth + 1) for i in _indices(len(value), 5)]
+    return {"type": type(value).__name__}
+
+
+def _stats(values):
+    """Bound statistical work to 1,000 evenly spaced observations; label the sample."""
+    if not len(values):
+        return {}
+    sample = pd.Series(values).iloc[_indices(len(values), 1000)]
+    result = {
+        "observations": len(sample),
+        "sampled": len(sample) < len(values),
+        "missing": int(sample.isna().sum()),
+    }
+    if pd.api.types.is_numeric_dtype(sample.dtype) and not pd.api.types.is_complex_dtype(
+        sample.dtype
+    ):
+        numeric = sample.to_numpy(dtype=float, na_value=np.nan)
+        finite = numeric[np.isfinite(numeric)]
+        if len(finite):
+            # Scale first to avoid overflow while averaging large, finite values.
+            scale = float(np.abs(finite).max()) or 1.0
+            normalized = finite / scale
+            result.update(
+                min=float(finite.min()),
+                max=float(finite.max()),
+                mean=float(normalized.mean()) * scale,
+            )
+            if len(finite) > 1:
+                result["std"] = _value(float(normalized.std(ddof=1)) * scale)
+    return result
+
+
+def profile_data(data, *, sample_rows=5, max_chars=20_000):
+    """Return a profile capped by serialized character count, never a sliced JSON string."""
+    if not isinstance(sample_rows, int) or not 0 <= sample_rows <= 100:
+        raise ValueError("sample_rows must be an integer between 0 and 100.")
+    if not isinstance(max_chars, int) or not 500 <= max_chars <= 100_000:
+        raise ValueError("max_chars must be between 500 and 100,000.")
+    validate_data(data)
+    node_count = 0
+
+    def describe(value, depth=0):
+        nonlocal node_count
+        node_count += 1
+        result = {"type": type(value).__name__}
+        if depth >= 6 or node_count > 300:
+            return {**result, "truncated": True}
+        if isinstance(value, pd.DataFrame):
+            result.update(
+                shape=list(value.shape),
+                index_type=type(value.index).__name__,
+                index_names=[_value(name) for name in value.index.names],
+            )
+            result["columns"] = [
+                {
+                    "name": _value(value.columns[i]),
+                    "dtype": str(value.iloc[:, i].dtype),
+                    "stats": _stats(value.iloc[:, i]),
+                }
+                for i in range(min(len(value.columns), 100))
+            ]
+            result["sample_rows"] = [
+                {
+                    "index": _value(value.index[i]),
+                    "values": [_value(x) for x in value.iloc[i, :100]],
+                }
+                for i in _indices(len(value), sample_rows)
+            ]
+            if len(value.columns) > 100:
+                result["truncated"] = True
+        elif isinstance(value, pd.Series):
+            result.update(
+                length=len(value),
+                name=_value(value.name),
+                dtype=str(value.dtype),
+                stats=_stats(value),
+                sample=[
+                    {"index": _value(value.index[i]), "value": _value(value.iloc[i])}
+                    for i in _indices(len(value), sample_rows)
+                ],
+            )
+        elif isinstance(value, np.ndarray):
+            result.update(
+                shape=list(value.shape),
+                dtype=str(value.dtype),
+                sample=[_value(value[i]) for i in _indices(len(value), sample_rows)],
+            )
+            if value.ndim == 1:
+                result["stats"] = _stats(value)
+        elif isinstance(value, dict):
+            result.update(
+                length=len(value),
+                items=[
+                    {"key": _value(key), "value": describe(item, depth + 1)}
+                    for key, item in islice(value.items(), 100)
+                ],
+            )
+            if len(value) > 100:
+                result["truncated"] = True
+        elif isinstance(value, (list, tuple)):
+            result.update(
+                length=len(value),
+                sample=[
+                    {"position": i, "value": describe(value[i], depth + 1)}
+                    for i in _indices(len(value), sample_rows)
+                ],
+            )
+            if value and all(isinstance(v, (int, float, np.number)) for v in value):
+                result["stats"] = _stats(value)
+        else:
+            result["value"] = _value(value)
+        return result
+
+    profile = {"profile_version": 1, "data": describe(data)}
+
+    def shrink(node):
+        candidates = []
+        if isinstance(node, dict):
+            for key, value in node.items():
+                if isinstance(value, list) and value:
+                    candidates.append((len(json.dumps(value, default=str)), node, key))
+                candidates.extend(shrink(value))
+        elif isinstance(node, list):
+            for value in node:
+                candidates.extend(shrink(value))
+        return candidates
+
+    while len(json.dumps(profile, ensure_ascii=True)) > max_chars:
+        candidates = shrink(profile)
+        profile["truncated"] = True
+        if not candidates:
+            profile = {
+                "profile_version": 1,
+                "data": {"type": type(data).__name__},
+                "truncated": True,
+            }
+            break
+        _, parent, key = max(candidates, key=lambda candidate: candidate[0])
+        parent[key] = parent[key][: len(parent[key]) // 2]
+        parent["truncated"] = True
+    return profile