dqscore 0.1.0__py3-none-any.whl

dqscore/__init__.py

@@ -0,0 +1,40 @@
+"""dqscore — a lightweight data quality toolkit for pandas.
+
+Quick start
+-----------
+>>> import pandas as pd
+>>> import dqscore as dq
+>>> df = pd.DataFrame({"id": [1, 2, 2], "age": [30, -1, 41]})
+>>> result = dq.auto_scan(df)
+>>> result.passed
+False
+
+Declare expectations explicitly with a :class:`~dqscore.Schema`::
+
+    schema = dq.Schema("people")
+    schema.column("id").not_null().unique()
+    schema.column("age").in_range(0, 120)
+    report = schema.validate(df)
+    print(report.summary())
+"""
+from __future__ import annotations
+
+from . import checks
+from .autoscan import auto_scan
+from .profiling import Profile, profile
+from .report import CheckResult, ValidationResult
+from .validator import ColumnSchema, Schema
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Schema",
+    "ColumnSchema",
+    "profile",
+    "Profile",
+    "auto_scan",
+    "ValidationResult",
+    "CheckResult",
+    "checks",
+    "__version__",
+]

dqscore/autoscan.py

@@ -0,0 +1,60 @@
+"""Zero-config quality scan: infer sensible default checks for any DataFrame."""
+from __future__ import annotations
+
+from typing import Optional
+
+import pandas as pd
+
+from .report import ValidationResult
+from .validator import Schema
+
+__all__ = ["auto_scan"]
+
+
+def _looks_like_id(name: str) -> bool:
+    lowered = str(name).lower()
+    return lowered == "id" or lowered.endswith("_id") or lowered.endswith("id")
+
+
+def auto_scan(
+    df: pd.DataFrame,
+    max_null_pct: float = 0.0,
+    name: str = "auto_scan",
+) -> ValidationResult:
+    """Run a quick, opinionated quality scan with no schema required.
+
+    Heuristics applied:
+
+    * every column is expected to have at most ``max_null_pct`` percent nulls;
+    * columns that look like identifiers (``id`` / ``*_id``) are expected to be
+      unique;
+    * the frame is expected to have no fully duplicated rows.
+
+    Parameters
+    ----------
+    df:
+        The DataFrame to scan.
+    max_null_pct:
+        Allowed percentage of nulls per column before the column's null check
+        fails. ``0.0`` means "no nulls allowed".
+    """
+    if not isinstance(df, pd.DataFrame):
+        raise TypeError("auto_scan() expects a pandas DataFrame")
+
+    n = len(df)
+    threshold = max_null_pct / 100.0
+    schema = Schema(name)
+
+    for col in df.columns:
+        series = df[col]
+        null_frac = series.isna().mean() if n else 0.0
+        if null_frac > threshold:
+            # Flag missingness explicitly via the not_null check.
+            schema.column(col).not_null()
+        if _looks_like_id(col):
+            # Identifier-like columns are expected to be unique; this surfaces
+            # accidental duplicate keys, a common data quality defect.
+            schema.column(col).unique()
+
+    schema.no_duplicate_rows()
+    return schema.validate(df)

dqscore/checks.py

@@ -0,0 +1,127 @@
+"""Low-level data quality checks.
+
+Every check takes a :class:`pandas.Series` (or DataFrame, for frame-level
+checks) and returns a boolean mask aligned to the input where ``True`` marks a
+*failing* row. Null handling is deliberate: most checks let nulls pass so that
+``not_null`` is the single source of truth for missing values. Combine checks to
+express richer expectations.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Iterable, Optional
+
+import pandas as pd
+
+__all__ = [
+    "not_null",
+    "unique",
+    "in_range",
+    "in_set",
+    "matches",
+    "is_numeric",
+    "is_integer",
+    "is_datetime",
+    "string_length",
+    "no_duplicate_rows",
+]
+
+
+def _as_bool_mask(mask: pd.Series, index: pd.Index) -> pd.Series:
+    """Coerce a mask to a clean boolean Series aligned to ``index``."""
+    return pd.Series(mask, index=index).fillna(False).astype(bool)
+
+
+def not_null(series: pd.Series) -> pd.Series:
+    """Fail rows whose value is null / NaN / NaT."""
+    return series.isna()
+
+
+def unique(series: pd.Series) -> pd.Series:
+    """Fail rows whose (non-null) value appears more than once."""
+    duplicated = series.duplicated(keep=False)
+    return _as_bool_mask(duplicated & series.notna(), series.index)
+
+
+def in_range(
+    series: pd.Series,
+    min_value: Optional[float] = None,
+    max_value: Optional[float] = None,
+    inclusive: bool = True,
+) -> pd.Series:
+    """Fail rows outside ``[min_value, max_value]``.
+
+    Non-numeric, non-null values fail as well. Nulls pass (use ``not_null``).
+    """
+    numeric = pd.to_numeric(series, errors="coerce")
+    fail = pd.Series(False, index=series.index)
+    if min_value is not None:
+        fail |= (numeric < min_value) if inclusive else (numeric <= min_value)
+    if max_value is not None:
+        fail |= (numeric > max_value) if inclusive else (numeric >= max_value)
+    non_numeric = numeric.isna() & series.notna()
+    fail |= non_numeric
+    return _as_bool_mask(fail, series.index)
+
+
+def in_set(series: pd.Series, allowed: Iterable[Any]) -> pd.Series:
+    """Fail rows whose (non-null) value is not in ``allowed``."""
+    allowed_set = set(allowed)
+    fail = ~series.isin(allowed_set) & series.notna()
+    return _as_bool_mask(fail, series.index)
+
+
+def matches(series: pd.Series, pattern: str, full_match: bool = False) -> pd.Series:
+    """Fail rows whose (non-null) string value does not match ``pattern``."""
+    compiled = re.compile(pattern)
+    finder = compiled.fullmatch if full_match else compiled.search
+
+    def _fails(value: Any) -> bool:
+        if pd.isna(value):
+            return False
+        return finder(str(value)) is None
+
+    return _as_bool_mask(series.map(_fails), series.index)
+
+
+def is_numeric(series: pd.Series) -> pd.Series:
+    """Fail non-null values that cannot be parsed as numbers."""
+    coerced = pd.to_numeric(series, errors="coerce")
+    return _as_bool_mask(coerced.isna() & series.notna(), series.index)
+
+
+def is_integer(series: pd.Series) -> pd.Series:
+    """Fail non-null values that are not whole numbers."""
+    coerced = pd.to_numeric(series, errors="coerce")
+    non_numeric = coerced.isna() & series.notna()
+    non_integer = coerced.notna() & (coerced % 1 != 0)
+    return _as_bool_mask(non_numeric | non_integer, series.index)
+
+
+def is_datetime(series: pd.Series, fmt: Optional[str] = None) -> pd.Series:
+    """Fail non-null values that cannot be parsed as dates/times."""
+    coerced = pd.to_datetime(series, errors="coerce", format=fmt)
+    return _as_bool_mask(coerced.isna() & series.notna(), series.index)
+
+
+def string_length(
+    series: pd.Series,
+    min_len: Optional[int] = None,
+    max_len: Optional[int] = None,
+) -> pd.Series:
+    """Fail non-null values whose string length is outside the bounds."""
+    lengths = series.dropna().astype(str).str.len()
+    fail = pd.Series(False, index=series.index)
+    if min_len is not None:
+        fail.loc[lengths.index] |= lengths < min_len
+    if max_len is not None:
+        fail.loc[lengths.index] |= lengths > max_len
+    return _as_bool_mask(fail, series.index)
+
+
+def no_duplicate_rows(
+    df: pd.DataFrame, subset: Optional[Iterable[str]] = None
+) -> pd.Series:
+    """Fail rows that are exact duplicates (optionally over ``subset``)."""
+    subset_list = list(subset) if subset is not None else None
+    return _as_bool_mask(df.duplicated(subset=subset_list, keep=False), df.index)

dqscore/cli.py

@@ -0,0 +1,80 @@
+"""Command-line interface: ``dqscore profile|scan path.csv``."""
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional
+
+import pandas as pd
+
+from . import __version__, auto_scan, profile
+
+
+def _read(path: str, sep: Optional[str]) -> pd.DataFrame:
+    return pd.read_csv(path, sep=sep) if sep else pd.read_csv(path)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="dqscore",
+        description="Lightweight data quality toolkit for tabular data.",
+    )
+    parser.add_argument("--version", action="version",
+                        version=f"dqscore {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("path", help="Path to a CSV/TSV file.")
+    common.add_argument("--sep", default=None, help="Field separator (e.g. '\\t').")
+    common.add_argument("--html", metavar="FILE", help="Write an HTML report.")
+    common.add_argument("--json", metavar="FILE", help="Write a JSON report.")
+
+    p_profile = sub.add_parser("profile", parents=[common],
+                               help="Profile every column of the file.")
+    p_profile.add_argument("--markdown", metavar="FILE",
+                           help="Write a Markdown profile.")
+
+    p_scan = sub.add_parser("scan", parents=[common],
+                            help="Run a zero-config quality scan.")
+    p_scan.add_argument("--max-null-pct", type=float, default=0.0,
+                        help="Allowed %% of nulls per column (default 0).")
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = _build_parser().parse_args(argv)
+
+    try:
+        df = _read(args.path, args.sep)
+    except Exception as exc:  # pragma: no cover - user input errors
+        print(f"error: could not read {args.path}: {exc}", file=sys.stderr)
+        return 2
+
+    if args.command == "profile":
+        prof = profile(df)
+        print(prof.to_markdown())
+        if getattr(args, "markdown", None):
+            with open(args.markdown, "w", encoding="utf-8") as fh:
+                fh.write(prof.to_markdown())
+        if args.html:
+            prof.to_html(args.html)
+        if args.json:
+            import json
+
+            with open(args.json, "w", encoding="utf-8") as fh:
+                json.dump(prof.to_dict(), fh, indent=2, default=str)
+        return 0
+
+    # scan
+    result = auto_scan(df, max_null_pct=args.max_null_pct)
+    print(result.summary())
+    if args.html:
+        result.to_html(args.html)
+    if args.json:
+        with open(args.json, "w", encoding="utf-8") as fh:
+            fh.write(result.to_json())
+    return 0 if result.passed else 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

dqscore/profiling.py

@@ -0,0 +1,134 @@
+"""Lightweight DataFrame profiling: per-column stats, missingness, outliers."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from html import escape
+from typing import Any, Dict, List, Optional
+
+import pandas as pd
+
+__all__ = ["profile", "Profile"]
+
+
+@dataclass
+class Profile:
+    """Result of :func:`profile`, with export helpers."""
+
+    columns: List[Dict[str, Any]]
+    n_rows: int
+    n_cols: int
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "n_rows": self.n_rows,
+            "n_cols": self.n_cols,
+            "columns": self.columns,
+        }
+
+    def to_frame(self) -> pd.DataFrame:
+        """Return the profile as a tidy DataFrame (one row per column)."""
+        return pd.DataFrame(self.columns)
+
+    def to_markdown(self) -> str:
+        df = self.to_frame()
+        cols = [c for c in ["column", "dtype", "missing", "missing_pct",
+                            "unique", "distinct_pct", "mean", "min", "max",
+                            "outliers_iqr", "top_value"] if c in df.columns]
+        lines = [
+            f"# Data Profile — {self.n_rows} rows × {self.n_cols} columns",
+            "",
+            "| " + " | ".join(cols) + " |",
+            "| " + " | ".join(["---"] * len(cols)) + " |",
+        ]
+        for _, row in df[cols].iterrows():
+            lines.append("| " + " | ".join(str(row[c]) for c in cols) + " |")
+        return "\n".join(lines)
+
+    def to_html(self, path: Optional[str] = None) -> str:
+        table = self.to_frame().to_html(index=False, na_rep="", border=0)
+        html = f"""<!DOCTYPE html>
+<html lang="en"><head><meta charset="utf-8"><title>Data Profile</title>
+<style>
+ body {{ font-family:-apple-system,Segoe UI,Roboto,sans-serif; margin:2rem;
+        color:#1f2328; }}
+ h1 {{ font-size:1.4rem; }}
+ table {{ border-collapse:collapse; width:100%; font-size:.88rem; }}
+ th,td {{ border-bottom:1px solid #d0d7de; padding:.45rem .6rem;
+          text-align:left; }}
+ th {{ background:#f6f8fa; position:sticky; top:0; }}
+</style></head><body>
+<h1>Data Profile — {self.n_rows} rows × {self.n_cols} columns</h1>
+{table}
+</body></html>"""
+        if path:
+            with open(path, "w", encoding="utf-8") as fh:
+                fh.write(html)
+        return html
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return f"<Profile rows={self.n_rows} cols={self.n_cols}>"
+
+
+def _round(value: Any, n: int = 4) -> Any:
+    try:
+        return round(float(value), n)
+    except (TypeError, ValueError):
+        return value
+
+
+def profile(df: pd.DataFrame) -> Profile:
+    """Build a per-column profile of ``df``.
+
+    For numeric columns this adds descriptive statistics and an IQR-based
+    outlier count. For other columns it records the most frequent value.
+    """
+    if not isinstance(df, pd.DataFrame):
+        raise TypeError("profile() expects a pandas DataFrame")
+
+    n = len(df)
+    columns: List[Dict[str, Any]] = []
+
+    for col in df.columns:
+        s = df[col]
+        missing = int(s.isna().sum())
+        nunique = int(s.nunique(dropna=True))
+        info: Dict[str, Any] = {
+            "column": str(col),
+            "dtype": str(s.dtype),
+            "count": int(s.count()),
+            "missing": missing,
+            "missing_pct": _round(missing / n * 100, 2) if n else 0.0,
+            "unique": nunique,
+            "distinct_pct": _round(nunique / n * 100, 2) if n else 0.0,
+        }
+
+        if pd.api.types.is_numeric_dtype(s) and not pd.api.types.is_bool_dtype(s):
+            numeric = s.dropna()
+            if len(numeric):
+                q1, q3 = numeric.quantile(0.25), numeric.quantile(0.75)
+                iqr = q3 - q1
+                low, high = q1 - 1.5 * iqr, q3 + 1.5 * iqr
+                outliers = int(((numeric < low) | (numeric > high)).sum())
+                info.update(
+                    {
+                        "mean": _round(numeric.mean()),
+                        "std": _round(numeric.std()),
+                        "min": _round(numeric.min()),
+                        "q25": _round(q1),
+                        "median": _round(numeric.median()),
+                        "q75": _round(q3),
+                        "max": _round(numeric.max()),
+                        "zeros": int((numeric == 0).sum()),
+                        "negatives": int((numeric < 0).sum()),
+                        "outliers_iqr": outliers,
+                    }
+                )
+        else:
+            vc = s.value_counts(dropna=True)
+            if len(vc):
+                info["top_value"] = str(vc.index[0])
+                info["top_freq"] = int(vc.iloc[0])
+
+        columns.append(info)
+
+    return Profile(columns=columns, n_rows=n, n_cols=df.shape[1])

dqscore/report.py

@@ -0,0 +1,199 @@
+"""Result objects for validation runs, with scoring and export helpers."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from html import escape
+from typing import Any, Dict, List, Optional
+
+__all__ = ["CheckResult", "ValidationResult"]
+
+
+@dataclass
+class CheckResult:
+    """Outcome of a single check against a single column (or the frame)."""
+
+    check: str
+    column: str
+    passed: bool
+    n_failing: int
+    n_total: int
+    params: Dict[str, Any] = field(default_factory=dict)
+    failing_index: List[Any] = field(default_factory=list)
+    sample_values: List[Any] = field(default_factory=list)
+    message: str = ""
+
+    @property
+    def pass_rate(self) -> float:
+        """Fraction of rows that satisfied this check (0.0 - 1.0)."""
+        if self.n_total == 0:
+            return 1.0
+        return (self.n_total - self.n_failing) / self.n_total
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "check": self.check,
+            "column": self.column,
+            "passed": self.passed,
+            "n_failing": self.n_failing,
+            "n_total": self.n_total,
+            "pass_rate": round(self.pass_rate, 4),
+            "params": self.params,
+            "failing_index": [str(i) for i in self.failing_index],
+            "sample_values": [_safe(v) for v in self.sample_values],
+            "message": self.message,
+        }
+
+
+@dataclass
+class ValidationResult:
+    """Aggregated outcome of validating a DataFrame against a schema."""
+
+    results: List[CheckResult]
+    n_rows: int
+    schema_name: str = "schema"
+
+    # -- summary properties -------------------------------------------------
+    @property
+    def passed(self) -> bool:
+        return all(r.passed for r in self.results)
+
+    @property
+    def n_checks(self) -> int:
+        return len(self.results)
+
+    @property
+    def n_passed(self) -> int:
+        return sum(1 for r in self.results if r.passed)
+
+    @property
+    def n_failed(self) -> int:
+        return self.n_checks - self.n_passed
+
+    @property
+    def score(self) -> float:
+        """Percentage of checks that passed (0 - 100)."""
+        if not self.results:
+            return 100.0
+        return round(self.n_passed / self.n_checks * 100, 2)
+
+    @property
+    def failures(self) -> List[CheckResult]:
+        return [r for r in self.results if not r.passed]
+
+    # -- exports ------------------------------------------------------------
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "schema": self.schema_name,
+            "passed": self.passed,
+            "score": self.score,
+            "n_rows": self.n_rows,
+            "n_checks": self.n_checks,
+            "n_passed": self.n_passed,
+            "n_failed": self.n_failed,
+            "results": [r.to_dict() for r in self.results],
+        }
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent, default=_safe)
+
+    def summary(self) -> str:
+        status = "PASSED" if self.passed else "FAILED"
+        lines = [
+            f"Data Quality Report  -  schema: {self.schema_name}",
+            "=" * 52,
+            f"Status : {status}",
+            f"Score  : {self.score}%  ({self.n_passed}/{self.n_checks} checks)",
+            f"Rows   : {self.n_rows}",
+            "-" * 52,
+        ]
+        for r in self.results:
+            mark = "PASS" if r.passed else "FAIL"
+            detail = "" if r.passed else f"  ({r.n_failing} failing)"
+            lines.append(f"[{mark}] {r.column}.{r.check}{detail}")
+        return "\n".join(lines)
+
+    def to_markdown(self) -> str:
+        status = "PASSED" if self.passed else "FAILED"
+        lines = [
+            f"# Data Quality Report — `{self.schema_name}`",
+            "",
+            f"**Status:** {status}  ·  **Score:** {self.score}%  "
+            f"·  **Checks:** {self.n_passed}/{self.n_checks} passed  "
+            f"·  **Rows:** {self.n_rows}",
+            "",
+            "| Status | Column | Check | Failing | Pass rate |",
+            "| :----: | ------ | ----- | ------: | --------: |",
+        ]
+        for r in self.results:
+            mark = "✅" if r.passed else "❌"
+            lines.append(
+                f"| {mark} | `{r.column}` | {r.check} | "
+                f"{r.n_failing} | {r.pass_rate:.1%} |"
+            )
+        return "\n".join(lines)
+
+    def to_html(self, path: Optional[str] = None) -> str:
+        rows = []
+        for r in self.results:
+            color = "#1a7f37" if r.passed else "#cf222e"
+            mark = "PASS" if r.passed else "FAIL"
+            rows.append(
+                f"<tr><td style='color:{color};font-weight:600'>{mark}</td>"
+                f"<td><code>{escape(str(r.column))}</code></td>"
+                f"<td>{escape(r.check)}</td>"
+                f"<td style='text-align:right'>{r.n_failing}</td>"
+                f"<td style='text-align:right'>{r.pass_rate:.1%}</td></tr>"
+            )
+        status = "PASSED" if self.passed else "FAILED"
+        status_color = "#1a7f37" if self.passed else "#cf222e"
+        html = f"""<!DOCTYPE html>
+<html lang="en"><head><meta charset="utf-8">
+<title>DQ Report - {escape(self.schema_name)}</title>
+<style>
+ body {{ font-family: -apple-system, Segoe UI, Roboto, sans-serif;
+        margin: 2rem; color: #1f2328; }}
+ h1 {{ font-size: 1.4rem; }}
+ .badge {{ display:inline-block; padding:.2rem .6rem; border-radius:6px;
+           color:#fff; font-weight:600; background:{status_color}; }}
+ table {{ border-collapse: collapse; width: 100%; margin-top: 1rem; }}
+ th, td {{ border-bottom: 1px solid #d0d7de; padding: .5rem .75rem;
+           text-align: left; font-size: .92rem; }}
+ th {{ background:#f6f8fa; }}
+ .meta {{ color:#57606a; margin:.5rem 0 1rem; }}
+</style></head><body>
+<h1>Data Quality Report — {escape(self.schema_name)}</h1>
+<p><span class="badge">{status}</span></p>
+<p class="meta">Score {self.score}% · {self.n_passed}/{self.n_checks} checks
+ passed · {self.n_rows} rows</p>
+<table><thead><tr><th>Status</th><th>Column</th><th>Check</th>
+<th style="text-align:right">Failing</th>
+<th style="text-align:right">Pass rate</th></tr></thead>
+<tbody>{''.join(rows)}</tbody></table>
+</body></html>"""
+        if path:
+            with open(path, "w", encoding="utf-8") as fh:
+                fh.write(html)
+        return html
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return (
+            f"<ValidationResult passed={self.passed} score={self.score}% "
+            f"checks={self.n_passed}/{self.n_checks}>"
+        )
+
+
+def _safe(value: Any) -> Any:
+    """Make numpy / pandas scalars JSON-serialisable."""
+    try:
+        import numpy as np
+
+        if isinstance(value, np.generic):
+            return value.item()
+    except Exception:  # pragma: no cover
+        pass
+    if value is None:
+        return None
+    if isinstance(value, (str, int, float, bool)):
+        return value
+    return str(value)

dqscore/validator.py

@@ -0,0 +1,189 @@
+"""A small, fluent schema API for declaring expectations and validating data.
+
+Example
+-------
+>>> import dqscore as dq
+>>> schema = dq.Schema("customers")
+>>> schema.column("id").not_null().unique()
+>>> schema.column("age").in_range(0, 120)
+>>> schema.column("email").matches(r"^[^@]+@[^@]+\\.[^@]+$")
+>>> schema.no_duplicate_rows()
+>>> result = schema.validate(df)          # doctest: +SKIP
+>>> print(result.summary())               # doctest: +SKIP
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Iterable, List, Optional, Tuple
+
+import pandas as pd
+
+from . import checks
+from .report import CheckResult, ValidationResult
+
+__all__ = ["Schema", "ColumnSchema"]
+
+# A registered check: display name, function(series)->mask, params for the report
+_ColumnCheck = Tuple[str, Callable[[pd.Series], pd.Series], Dict[str, Any]]
+_FrameCheck = Tuple[str, Callable[[pd.DataFrame], pd.Series], Dict[str, Any]]
+
+
+class ColumnSchema:
+    """Collects the checks declared for a single column. Methods chain."""
+
+    def __init__(self, name: str, parent: "Schema") -> None:
+        self.name = name
+        self._parent = parent
+        self._checks: List[_ColumnCheck] = []
+        self.required = True
+
+    def _add(self, name: str, fn: Callable[[pd.Series], pd.Series], **params: Any):
+        self._checks.append((name, fn, params))
+        return self
+
+    # -- expectations -------------------------------------------------------
+    def not_null(self) -> "ColumnSchema":
+        return self._add("not_null", checks.not_null)
+
+    def unique(self) -> "ColumnSchema":
+        return self._add("unique", checks.unique)
+
+    def in_range(
+        self,
+        min_value: Optional[float] = None,
+        max_value: Optional[float] = None,
+        inclusive: bool = True,
+    ) -> "ColumnSchema":
+        return self._add(
+            "in_range",
+            lambda s: checks.in_range(s, min_value, max_value, inclusive),
+            min_value=min_value,
+            max_value=max_value,
+            inclusive=inclusive,
+        )
+
+    def in_set(self, allowed: Iterable[Any]) -> "ColumnSchema":
+        allowed = list(allowed)
+        return self._add("in_set", lambda s: checks.in_set(s, allowed), allowed=allowed)
+
+    def matches(self, pattern: str, full_match: bool = False) -> "ColumnSchema":
+        return self._add(
+            "matches",
+            lambda s: checks.matches(s, pattern, full_match),
+            pattern=pattern,
+            full_match=full_match,
+        )
+
+    def is_numeric(self) -> "ColumnSchema":
+        return self._add("is_numeric", checks.is_numeric)
+
+    def is_integer(self) -> "ColumnSchema":
+        return self._add("is_integer", checks.is_integer)
+
+    def is_datetime(self, fmt: Optional[str] = None) -> "ColumnSchema":
+        return self._add("is_datetime", lambda s: checks.is_datetime(s, fmt), fmt=fmt)
+
+    def string_length(
+        self, min_len: Optional[int] = None, max_len: Optional[int] = None
+    ) -> "ColumnSchema":
+        return self._add(
+            "string_length",
+            lambda s: checks.string_length(s, min_len, max_len),
+            min_len=min_len,
+            max_len=max_len,
+        )
+
+    def custom(
+        self, fn: Callable[[pd.Series], pd.Series], name: str = "custom"
+    ) -> "ColumnSchema":
+        """Register a user function returning a mask (``True`` == failing)."""
+        return self._add(name, fn)
+
+    # -- convenience to keep chaining onto the schema ----------------------
+    def column(self, name: str) -> "ColumnSchema":
+        return self._parent.column(name)
+
+
+class Schema:
+    """A collection of column- and frame-level expectations."""
+
+    def __init__(self, name: str = "schema") -> None:
+        self.name = name
+        self._columns: Dict[str, ColumnSchema] = {}
+        self._frame_checks: List[_FrameCheck] = []
+
+    def column(self, name: str) -> ColumnSchema:
+        """Return (creating if needed) the schema for ``name``."""
+        if name not in self._columns:
+            self._columns[name] = ColumnSchema(name, self)
+        return self._columns[name]
+
+    def no_duplicate_rows(
+        self, subset: Optional[Iterable[str]] = None
+    ) -> "Schema":
+        subset = list(subset) if subset is not None else None
+        self._frame_checks.append(
+            (
+                "no_duplicate_rows",
+                lambda df: checks.no_duplicate_rows(df, subset),
+                {"subset": subset},
+            )
+        )
+        return self
+
+    def validate(self, df: pd.DataFrame) -> ValidationResult:
+        """Run every declared check against ``df`` and collect the results."""
+        if not isinstance(df, pd.DataFrame):
+            raise TypeError("validate() expects a pandas DataFrame")
+
+        results: List[CheckResult] = []
+        n_total = len(df)
+
+        for col_name, col in self._columns.items():
+            if col_name not in df.columns:
+                if col.required:
+                    results.append(
+                        CheckResult(
+                            check="column_exists",
+                            column=col_name,
+                            passed=False,
+                            n_failing=n_total,
+                            n_total=n_total,
+                            message=f"Column '{col_name}' is missing.",
+                        )
+                    )
+                continue
+
+            series = df[col_name]
+            for check_name, fn, params in col._checks:
+                mask = checks._as_bool_mask(fn(series), series.index)
+                n_failing = int(mask.sum())
+                failing_idx = list(df.index[mask][:10])
+                results.append(
+                    CheckResult(
+                        check=check_name,
+                        column=col_name,
+                        passed=n_failing == 0,
+                        n_failing=n_failing,
+                        n_total=n_total,
+                        params=params,
+                        failing_index=failing_idx,
+                        sample_values=list(series[mask].head(10)),
+                    )
+                )
+
+        for check_name, fn, params in self._frame_checks:
+            mask = checks._as_bool_mask(fn(df), df.index)
+            n_failing = int(mask.sum())
+            results.append(
+                CheckResult(
+                    check=check_name,
+                    column="<frame>",
+                    passed=n_failing == 0,
+                    n_failing=n_failing,
+                    n_total=n_total,
+                    params=params,
+                    failing_index=list(df.index[mask][:10]),
+                )
+            )
+
+        return ValidationResult(results=results, n_rows=n_total, schema_name=self.name)

dqscore-0.1.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: dqscore
+Version: 0.1.0
+Summary: A lightweight data quality toolkit for pandas: profiling, validation schemas, and a zero-config scan.
+Author-email: YOUR NAME <you@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/YOUR_USERNAME/dqscore
+Project-URL: Repository, https://github.com/YOUR_USERNAME/dqscore
+Project-URL: Issues, https://github.com/YOUR_USERNAME/dqscore/issues
+Keywords: data-quality,pandas,validation,data-profiling,etl,dataframe
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.3
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# dqscore
+
+> A lightweight **data quality toolkit for pandas** — profile any DataFrame, declare
+> expectations with a fluent schema, or run a zero-config scan. No heavy dependencies,
+> no config files required.
+
+[![CI](https://github.com/dgvj-work/dqscore/actions/workflows/ci.yml/badge.svg)](https://github.com/dgvj-work/dqscore/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+`dqscore` helps you catch the boring-but-costly data problems — nulls where there
+shouldn't be any, duplicate keys, out-of-range values, malformed strings — before
+they reach a model, a dashboard, or a stakeholder.
+
+---
+## Why this exists ?
+Data quality issues are the silent killers of analytics and ML work. A null in the wrong column, a duplicate primary key, a value outside its expected range — these don't crash your pipeline. They quietly corrupt your output, and you find out three weeks later in a stakeholder meeting.
+The Python ecosystem already has excellent tools for this. Great Expectations is comprehensive and battle-tested. Pandera offers powerful schema-based validation. ydata-profiling produces rich exploratory reports. If you're building a long-lived production data platform, those are the right answers.
+But there's a gap in shape. When an analyst gets a fresh CSV and wants a fast read on whether it's trustworthy, the existing tools ask for a lot upfront — a schema, a config, a project structure, sometimes a framework integration. The lightest possible question — is this data OK? — doesn't have a one-line answer in any of them. And once you do set up checks, getting a single number you can put on a dashboard, or a non-zero exit code you can wire into CI, often needs custom code on top.
+dqscore is built for that middle ground. It has one dependency (pandas) and three things to learn: profile a DataFrame, declare a schema with a fluent API, or run a zero-config scan that infers sensible defaults. Every validation produces a 0–100 quality score and a report that exports to HTML, Markdown, or JSON. The CLI returns exit code 1 on failure, so dqscore scan data.csv drops straight into a CI pipeline or a pre-commit hook with no glue code.
+It's not a replacement for Great Expectations or pandera. It's the tool you reach for at the start of a project, or when reviewing a new dataset, or when you want a simple quality gate in CI without standing up a whole framework. That's the gap, and I think it's a useful one to fill — especially for individuals, smaller teams, and educators where the ceremony of heavier tools is the actual barrier to checking data at all.
+The package is MIT-licensed and feedback is welcome. If a check is missing, a report format would be useful, or the auto-scan heuristics could be smarter for your data, open an issue.
+
+---
+
+## Why dqscore?
+
+- **Tiny surface area.** Three things to learn: `profile`, `Schema`, `auto_scan`.
+- **Readable reports.** Every result exports to dict, JSON, Markdown, or styled HTML.
+- **Scoreable.** Each validation produces a 0–100 quality score for dashboards/CI.
+- **CLI included.** `dqscore scan data.csv` returns a non-zero exit code on failure,
+  so it drops straight into a pipeline or pre-commit hook.
+- **One dependency:** pandas.
+
+---
+
+## Installation
+
+```bash
+pip install dqscore
+```
+
+Or install the latest from source:
+
+```bash
+git clone https://github.com/dgvj-work/dqscore.git
+cd dqscore
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick start
+
+### 1. Profile a DataFrame
+
+```python
+import pandas as pd
+import dqscore as dq
+
+df = pd.read_csv("customers.csv")
+profile = dq.profile(df)
+
+print(profile.to_markdown())   # per-column stats
+profile.to_html("profile.html")
+```
+
+### 2. Validate against a schema
+
+```python
+schema = dq.Schema("customers")
+schema.column("id").not_null().unique()
+schema.column("age").in_range(0, 120)
+schema.column("email").matches(r"^[^@]+@[^@]+\.[^@]+$")
+schema.column("country").in_set(["US", "CA", "MX"])
+schema.no_duplicate_rows()
+
+result = schema.validate(df)
+
+print(result.summary())        # human-readable report
+print("Quality score:", result.score)
+result.to_html("dq_report.html")
+
+if not result.passed:
+    raise SystemExit("Data quality checks failed")
+```
+
+### 3. Zero-config scan
+
+When you just want a quick read on a new file:
+
+```python
+result = dq.auto_scan(df)       # checks nulls, duplicate keys, duplicate rows
+print(result.summary())
+```
+
+---
+
+## Command line
+
+```bash
+# Profile every column
+dqscore profile data.csv --html profile.html
+
+# Quick quality scan (exit code 1 if it fails — great for CI)
+dqscore scan data.csv --json report.json
+dqscore scan data.csv --max-null-pct 5
+```
+
+---
+
+## Available checks
+
+| Method                              | Fails when…                                  |
+| ----------------------------------- | -------------------------------------------- |
+| `not_null()`                        | value is null / NaN / NaT                    |
+| `unique()`                          | a non-null value occurs more than once       |
+| `in_range(min, max, inclusive)`     | numeric value is outside the bounds          |
+| `in_set([...])`                     | value is not one of the allowed values       |
+| `matches(pattern, full_match)`      | string does not match the regex              |
+| `is_numeric()` / `is_integer()`     | value can't be parsed as a number / integer  |
+| `is_datetime(fmt)`                  | value can't be parsed as a date/time         |
+| `string_length(min_len, max_len)`   | string length is out of bounds               |
+| `custom(fn, name)`                  | your function returns `True` for a row        |
+| `Schema.no_duplicate_rows(subset)`  | rows are exact duplicates                     |
+
+Checks chain on a column and most let nulls pass, so `not_null()` stays the single
+source of truth for missing values:
+
+```python
+schema.column("score").not_null().is_numeric().in_range(0, 100)
+```
+
+---
+
+## Reports & scoring
+
+A `ValidationResult` gives you:
+
+- `result.passed` — `True`/`False`
+- `result.score` — percentage of checks passed (0–100)
+- `result.failures` — only the failing checks (with sample failing values & indices)
+- `result.summary()` / `to_markdown()` / `to_json()` / `to_html(path)`
+
+---
+
+## Contributing
+
+Contributions and feedback are very welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
+Found a bug or want a new check? [Open an issue](https://github.com/dgvj-work/dqscore/issues).
+
+## License
+
+[MIT](LICENSE)

dqscore-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+dqscore/__init__.py,sha256=B2m7qEYsRqUXwiECq_tmb3O-QMF-zNymlp9-d45xURk,922
+dqscore/autoscan.py,sha256=69kngyUDK5dxqELPRjSp4WfdxJvVnUmT7KP9zwSy2MA,1810
+dqscore/checks.py,sha256=QVuuWHIxaoaOnSmDh-j4ds-8fxQywMi2-qLhenWqN1g,4398
+dqscore/cli.py,sha256=SpUTZ2YfJ6h9glMYCwalOKqYv7II5why_eKlSH33u0Q,2821
+dqscore/profiling.py,sha256=tABsjgQUYRRAnkCo6mhdH_YpWE31EEYUozSqcfohTvg,4733
+dqscore/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dqscore/report.py,sha256=nMuJS8ccYFUjP7VIdp01Ci8vdQjboG1z7pVgIGRAchg,6978
+dqscore/validator.py,sha256=Hcxky6g-b9nuXp1oQZG2La9QfhsCXBbhnUVWTDh5pgw,6751
+dqscore-0.1.0.dist-info/licenses/LICENSE,sha256=8vHK8oOyyleh7zi03oOw8La7y31Z3ik7qMnPatOPri4,1073
+dqscore-0.1.0.dist-info/METADATA,sha256=812mfKCi0wl1ENNDICiqeEwhpK9PuHP-AF8ZIHRsJXk,7875
+dqscore-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+dqscore-0.1.0.dist-info/entry_points.txt,sha256=ECYp7oL4KZz5nDtBCS78cYzY9fnY5gWL_MQRwuF8iFM,45
+dqscore-0.1.0.dist-info/top_level.txt,sha256=8_eTWrrK-QYmqumHL4p-2p5hW48SHxyx8nLyNv-byaE,8
+dqscore-0.1.0.dist-info/RECORD,,

dqscore-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dqscore-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dqscore = dqscore.cli:main

dqscore-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Digvijay Waghela
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dqscore-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dqscore