tabalyst 0.1.0__py3-none-any.whl

tabalyst/models.py

@@ -0,0 +1,174 @@
+"""Serializable analysis results, independent from presentation."""
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, FiniteFloat
+
+from tabalyst.config import AnalysisConfig
+
+
+class ResultModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class SourceInfo(ResultModel):
+    filename: str
+    size_bytes: int
+    sha256: str
+    encoding: str
+    delimiter: str
+
+
+class NumericStats(ResultModel):
+    minimum: FiniteFloat
+    maximum: FiniteFloat
+    mean: FiniteFloat
+    median: FiniteFloat
+
+
+class NormalizationStats(ResultModel):
+    trim_count: int
+    trim_percent: float
+    collapse_internal_whitespace_count: int
+    collapse_internal_whitespace_percent: float
+
+
+class DateFormatCount(ResultModel):
+    format: str
+    order: Literal["YMD", "MDY", "DMY"]
+    separator: str
+    count: int
+    percent: float
+    iso: bool = False
+
+
+class DateBreakdownItem(ResultModel):
+    label: str
+    category: Literal["valid", "ambiguous", "invalid", "not_date"]
+    count: int
+    percent: float
+
+
+class DateProfile(ResultModel):
+    status: Literal["valid", "multiple_formats", "mixed", "ambiguous", "invalid"]
+    valid_count: int
+    ambiguous_count: int
+    invalid_date_count: int
+    not_date_count: int
+    resolved_ambiguous_order: Literal["MDY", "DMY"] | None = None
+    ambiguous_order_source: Literal["config", "column"] | None = None
+    formats: list[DateFormatCount]
+    format_count: int
+    breakdown: list[DateBreakdownItem]
+    errors: dict[str, int]
+
+
+class StringLengthExample(ResultModel):
+    value: str
+    count: int
+
+
+class StringLengthDistribution(ResultModel):
+    length: int
+    count: int
+    percent: float
+    distinct_count: int
+    examples: list[StringLengthExample]
+
+
+class StringProfile(ResultModel):
+    status: Literal["very_short", "short", "medium", "long", "very_long"]
+    present_count: int
+    minimum_length: int
+    maximum_length: int
+    mean_length: FiniteFloat
+    median_length: FiniteFloat
+    distinct_length_count: int
+    fixed_length: int | None = None
+    length_distribution: list[StringLengthDistribution]
+
+
+class ValueOccurrence(ResultModel):
+    value: str
+    count: int
+    truncated: bool = False
+
+
+class ValueProfile(ResultModel):
+    selection: Literal["complete", "diverse_sample", "random_sample"]
+    sampled_distinct_count: int
+    values: list[ValueOccurrence]
+
+
+class EnumCandidate(ResultModel):
+    status: Literal["candidate"] = "candidate"
+    observed_distinct_count: int
+    non_missing_count: int
+    coverage_percent: float
+    confidence: float
+
+
+class ColumnProfile(ResultModel):
+    id: str
+    name: str
+    position: int
+    inferred_type: Literal[
+        "empty", "boolean", "integer", "number", "date", "text", "mixed"
+    ]
+    type_counts: dict[str, int]
+    type_confidence: float
+    type_error_count: int | None
+    type_error_percent: float | None
+    missing_count: int
+    missing_percent: float
+    normalization: NormalizationStats
+    distinct_count: int
+    examples: list[str]
+    value_profile: ValueProfile
+    semantic_type: Literal["enum", "date"] | None = None
+    enum: EnumCandidate | None = None
+    date_profile: DateProfile | None = None
+    string_profile: StringProfile | None = None
+    numeric: NumericStats | None = None
+
+
+class DatasetSummary(ResultModel):
+    row_count: int
+    column_count: int
+    cell_count: int
+    missing_count: int
+    missing_percent: float
+    trim_count: int
+    collapse_internal_whitespace_count: int
+    duplicate_row_count: int
+    empty_row_count: int
+    empty_column_count: int
+    constant_column_count: int
+
+
+class Issue(ResultModel):
+    code: str
+    severity: Literal["info", "warning"]
+    message: str
+    count: int
+    column_ids: list[str]
+    row_numbers: list[int]
+
+
+class PreviewRow(ResultModel):
+    row_number: int
+    values: list[str]
+
+
+class DatasetProfile(ResultModel):
+    format_version: Literal["0.1.0a"] = "0.1.0a"
+    format_revision: Literal[1] = 1
+    generated_at: datetime
+    processing_seconds: FiniteFloat
+    source: SourceInfo
+    config: AnalysisConfig
+    summary: DatasetSummary
+    columns: list[ColumnProfile]
+    issues: list[Issue]
+    preview: list[PreviewRow]

tabalyst/reporting.py

@@ -0,0 +1,54 @@
+"""Render self-contained analysis results as an interactive HTML report."""
+
+from collections import Counter
+from importlib.resources import files
+from pathlib import Path
+
+from jinja2 import Environment, StrictUndefined
+
+from tabalyst._version import get_version
+from tabalyst.models import DatasetProfile
+
+
+def format_number(number: float) -> str:
+    """Keep ordinary values readable and compact only genuinely large magnitudes."""
+    if abs(number) > 10**10:
+        return f"{number:.4e}"
+    return f"{number:,.4f}".rstrip("0").rstrip(".")
+
+
+def format_seconds(seconds: float) -> str:
+    """Display elapsed time with no more than two decimal places."""
+    return f"{seconds:.2f}".rstrip("0").rstrip(".")
+
+
+def format_size(size_bytes: int) -> str:
+    """Display source size in KB, switching to MB at one mebibyte."""
+    if size_bytes >= 1024**2:
+        return f"{size_bytes / 1024**2:.1f} MB"
+    return f"{size_bytes / 1024:.1f} KB"
+
+
+def load_profile(path: str | Path) -> DatasetProfile:
+    """Validate and load the experimental JSON profile format."""
+    return DatasetProfile.model_validate_json(Path(path).read_text(encoding="utf-8"))
+
+
+def render_report(profile: DatasetProfile) -> str:
+    """Render exclusively from serialized analysis results; CSV access is unnecessary."""
+    resources = files("tabalyst")
+    environment = Environment(autoescape=True, undefined=StrictUndefined)
+    environment.filters["count"] = lambda number: f"{number:,}"
+    environment.filters["number"] = format_number
+    environment.filters["seconds"] = format_seconds
+    environment.filters["size"] = format_size
+    template = environment.from_string(
+        resources.joinpath("templates/report.html").read_text(encoding="utf-8")
+    )
+    return template.render(
+        report=profile,
+        tabalyst_version=get_version(),
+        types=Counter(column.inferred_type for column in profile.columns),
+        theme_css=resources.joinpath("static/theme.css").read_text(encoding="utf-8"),
+        report_js=resources.joinpath("static/report.js").read_text(encoding="utf-8"),
+    )

tabalyst/service.py

@@ -0,0 +1,134 @@
+"""Public analysis boundary shared by Python callers and the CLI."""
+
+import json
+from collections.abc import Sequence
+from pathlib import Path
+from time import perf_counter
+from typing import Any
+
+from tabalyst.analysis import analyze_dataset
+from tabalyst.config import AnalysisConfig, resolve_config
+from tabalyst.errors import ConfigurationError, InputError, ReportError
+from tabalyst.execution_log import (
+    EXECUTION_LOG_NAME,
+    append_execution,
+    build_execution_entry,
+)
+from tabalyst.ingestion import read_csv
+from tabalyst.models import DatasetProfile
+from tabalyst.reporting import load_profile, render_report
+
+ConfigPath = str | Path | Sequence[str | Path]
+
+
+def analyze_csv(
+    path: str | Path, config: AnalysisConfig | None = None
+) -> DatasetProfile:
+    """Read and analyze one CSV without coupling callers to the CLI."""
+    config = config or AnalysisConfig()
+    started = perf_counter()
+    profile = analyze_dataset(read_csv(Path(path), config.csv), config)
+    profile.processing_seconds = round(perf_counter() - started, 4)
+    return profile
+
+
+def _config_paths(config_path: ConfigPath | None) -> list[Path]:
+    if config_path is None:
+        return []
+    if isinstance(config_path, (str, Path)):
+        paths = [Path(config_path)]
+    else:
+        paths = [Path(path) for path in config_path]
+    for path in paths:
+        if not path.exists():
+            raise ConfigurationError(f"Configuration file does not exist: {path}")
+        if not path.is_file():
+            raise ConfigurationError(f"Configuration path is not a file: {path}")
+    return paths
+
+
+def _validate_paths(
+    source: Path, report: Path, config_paths: list[Path]
+) -> tuple[Path, Path]:
+    if not source.exists():
+        raise InputError(f"CSV file does not exist: {source}")
+    if not source.is_file():
+        raise InputError(f"CSV path is not a file: {source}")
+    if report.suffix.lower() != ".html":
+        raise InputError("report_path must be a complete filename ending in .html")
+    if report.exists() and report.is_dir():
+        raise InputError(f"Report path is a directory: {report}")
+
+    json_report = report.with_suffix(".json")
+    execution_report = report.parent / EXECUTION_LOG_NAME
+    inputs = {source.resolve(), *(path.resolve() for path in config_paths)}
+    outputs = [report.resolve(), json_report.resolve(), execution_report.resolve()]
+    if len(set(outputs)) != len(outputs):
+        raise InputError("HTML and JSON report paths must be different.")
+    for output in outputs:
+        if output in inputs:
+            raise InputError(f"Report would overwrite an input file: {output}")
+    return json_report, execution_report
+
+
+def _write_text(path: Path, content: str) -> None:
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8", newline="\n")
+    except OSError as exc:
+        raise ReportError(f"Cannot write report file {path}: {exc}") from exc
+
+
+def analyze(
+    csv_path: str | Path,
+    report_path: str | Path,
+    separator: str | None = None,
+    encoding: str | None = None,
+    config_path: ConfigPath | None = None,
+) -> dict[str, Any]:
+    """Analyze one CSV, write sibling JSON/HTML reports and return the result.
+
+    Explicit ``separator`` and ``encoding`` values override configuration-file
+    values, which in turn override Tabalyst's built-in defaults.
+    """
+    started = perf_counter()
+    source = Path(csv_path)
+    report = Path(report_path)
+    config_paths = _config_paths(config_path)
+    json_report, execution_report = _validate_paths(source, report, config_paths)
+    config = resolve_config(
+        config_paths,
+        separator=separator,
+        encoding=encoding,
+    )
+
+    try:
+        profile = analyze_csv(source, config)
+    except InputError:
+        raise
+    except OSError as exc:
+        raise InputError(f"Cannot read CSV file {source}: {exc}") from exc
+
+    result = profile.model_dump(mode="json")
+    json_text = json.dumps(result, indent=2, ensure_ascii=False) + "\n"
+    _write_text(json_report, json_text)
+    try:
+        html = render_report(load_profile(json_report))
+    except OSError as exc:
+        raise ReportError(f"Cannot render HTML report {report}: {exc}") from exc
+    _write_text(report, html)
+    try:
+        entry = build_execution_entry(
+            source=source,
+            html_output=report,
+            json_output=json_report,
+            profile=profile,
+            total_seconds=perf_counter() - started,
+            git_directory=Path.cwd(),
+        )
+        append_execution(execution_report, entry)
+    except (OSError, ValueError) as exc:
+        raise ReportError(
+            f"Cannot update execution history {execution_report}: {exc}"
+        ) from exc
+    return result