tidytable-core 1.0.0__py3-none-any.whl

tidytable/__init__.py

@@ -0,0 +1,19 @@
+from . import xl
+from . import structural
+from . import parse
+from . import missing
+from . import dedup
+from . import merge
+from . import reconcile
+from . import profile
+
+__all__ = [
+    "xl",
+    "structural",
+    "parse",
+    "missing",
+    "dedup",
+    "merge",
+    "reconcile",
+    "profile"
+]

tidytable/dedup/__init__.py

@@ -0,0 +1,6 @@
+from .engine import absolute, partial
+
+__all__ = [
+    "absolute",
+    "partial"
+]

tidytable/dedup/engine.py

@@ -0,0 +1,17 @@
+import pandas as pd
+
+def absolute(df: pd.DataFrame) -> pd.DataFrame:
+    """Removes records where rows present duplicate values across every single key column."""
+    return df.drop_duplicates().reset_index(drop=True)
+
+def partial(df: pd.DataFrame, subset: list[str], keep: str = "latest", timestamp_col: str = None) -> pd.DataFrame:
+    """Resolves ledger data conflicts across target unique matching indexes."""
+    if keep in ["latest", "earliest"] and not timestamp_col:
+        raise ValueError("timestamp_col must be specified when keeping latest/earliest items.")
+        
+    working_df = df.copy()
+    if timestamp_col:
+        working_df = working_df.sort_values(by=timestamp_col, ascending=(keep == "earliest"))
+        
+    keep_policy = "first" if keep in ["latest", "earliest"] else keep
+    return working_df.drop_duplicates(subset=subset, keep=keep_policy).reset_index(drop=True)

tidytable/merge/__init__.py

@@ -0,0 +1,6 @@
+from .engine import fuzzy_vlookup, join_diagnose
+
+__all__ = [
+    "fuzzy_vlookup",
+    "join_diagnose"
+]

tidytable/merge/engine.py

@@ -0,0 +1,34 @@
+import pandas as pd
+from rapidfuzz import process
+
+def fuzzy_vlookup(left_df: pd.DataFrame, right_df: pd.DataFrame, left_on: str, right_on: str, threshold: float = 0.85) -> pd.DataFrame:
+    """Executes an error-tolerant database left-join using string similarity score profiles."""
+    ldf = left_df.copy()
+    rdf = right_df.copy()
+    
+    right_keys = rdf[right_on].dropna().astype(str).tolist()
+    match_map = {}
+    
+    for l_key in ldf[left_on].dropna().astype(str).unique():
+        best_match = process.extractOne(l_key, right_keys, score_cutoff=threshold * 100)
+        if best_match:
+            match_map[l_key] = best_match[0]
+            
+    ldf[f"_fuzzy_key_join"] = ldf[left_on].astype(str).map(match_map)
+    rdf[f"_fuzzy_key_join"] = rdf[right_on].astype(str)
+    
+    merged = pd.merge(ldf, rdf, on="_fuzzy_key_join", how="left").drop(columns=["_fuzzy_key_join"])
+    return merged
+
+def join_diagnose(left_df: pd.DataFrame, right_df: pd.DataFrame, left_on: str, right_on: str) -> dict:
+    """Runs a pre-flight assessment matrix map detailing alignment success chances."""
+    l_keys = set(left_df[left_on].dropna().unique())
+    r_keys = set(right_df[right_on].dropna().unique())
+    
+    unmatched = l_keys - r_keys
+    return {
+        "left_total_unique_keys": len(l_keys),
+        "right_total_unique_keys": len(r_keys),
+        "unmatched_left_keys_count": len(unmatched),
+        "type_alignment_match": left_df[left_on].dtype == right_df[right_on].dtype
+    }

tidytable/missing/__init__.py

@@ -0,0 +1,7 @@
+from .engine import drop_empty_cols, flag_absence, impute
+
+__all__ = [
+    "drop_empty_cols",
+    "flag_absence",
+    "impute"
+]

tidytable/missing/engine.py

@@ -0,0 +1,27 @@
+import pandas as pd
+import numpy as np
+
+def drop_empty_cols(df: pd.DataFrame, threshold: float = 0.50) -> pd.DataFrame:
+    """Prunes out layout dimension paths that present excess null counts."""
+    return df.dropna(axis=1, thresh=int((1 - threshold) * len(df)))
+
+def flag_absence(df: pd.DataFrame, columns: list[str]) -> pd.DataFrame:
+    """Appends binary indicator tracking indexes to document missing status items."""
+    new_df = df.copy()
+    for col in columns:
+        if col in new_df.columns:
+            new_df[f"{col}_is_missing"] = new_df[col].isna()
+    return new_df
+
+def impute(series: pd.Series, strategy: str = "median") -> pd.Series:
+    """Fills data holes safely based on chosen statistical profiles."""
+    s = series.copy()
+    if strategy == "mean":
+        fill_val = s.mean()
+    elif strategy == "median":
+        fill_val = s.median()
+    elif strategy == "mode":
+        fill_val = s.mode()[0] if not s.mode().empty else np.nan
+    else:
+        fill_val = strategy # Interpret as explicit fallback text/value
+    return s.fillna(fill_val)

tidytable/parse/__init__.py

@@ -0,0 +1,9 @@
+from .engine import dates, financials, boolean, repair_identifiers, handle_formula_ghosts
+
+__all__ = [
+    "dates",
+    "financials",
+    "boolean",
+    "repair_identifiers",
+    "handle_formula_ghosts"
+]

tidytable/parse/engine.py

@@ -0,0 +1,73 @@
+import pandas as pd
+import numpy as np
+from dateutil import parser as date_parser
+
+def financials(series: pd.Series) -> pd.Series:
+    """Extracts scalar numbers from extreme formatting configurations and bounds."""
+    def _clean(val):
+        if pd.isna(val): return np.nan
+        s = str(val).strip().replace(',', '')
+        if not s or s.lower() in ['nan', 'none', 'null', '']: return np.nan
+        
+        # Guard against raw exponential notations or infinite boundaries
+        if s.lower() in ['inf', '-inf', 'infinity']:
+            return np.inf if '-' not in s else -np.inf
+            
+        is_negative = ('(' in s and ')' in s) or ('-' in s)
+        s = s.replace('$', '').replace('€', '').replace('£', '').replace('(', '').replace(')', '').replace('-', '').strip()
+        
+        if not s: return np.nan
+        
+        # Handle scaling metrics multipliers safely
+        multiplier = 1
+        if s.lower().endswith('k'):
+            multiplier = 1_000
+            s = s[:-1]
+        elif s.lower().endswith('m'):
+            multiplier = 1_000_000
+            s = s[:-1]
+        elif s.lower().endswith('b'):
+            multiplier = 1_000_000_000
+            s = s[:-1]
+            
+        try:
+            num = float(s) * multiplier
+            return -num if is_negative else num
+        except ValueError:
+            return np.nan
+            
+    return series.apply(_clean)
+
+def dates(series: pd.Series, dayfirst: bool = False) -> pd.Series:
+    """Transforms fluid data variants down to ISO timestamps while guarding against out-of-bounds dates."""
+    def _parse(val):
+        if pd.isna(val) or str(val).strip() in ["", "NaT", "NaN", "None", "null"]: return pd.NaT
+        try:
+            return date_parser.parse(str(val), dayfirst=dayfirst)
+        except (ValueError, OverflowError, TypeError):
+            return pd.NaT
+    return series.apply(_parse)
+
+def handle_formula_ghosts(series: pd.Series, error_strategy: str = "coerce") -> pd.Series:
+    """Traps calculations failures from Excel and forces them to target null variables."""
+    ghost_strings = ["#VALUE!", "#REF!", "#DIV/0!", "#NAME?", "#N/A", "#NUM!", "#NULL!"]
+    return series.apply(lambda x: np.nan if str(x).strip().upper() in ghost_strings else x)
+
+def repair_identifiers(series: pd.Series, pad_length: int = None) -> pd.Series:
+    """Restores dropped leading zeroes on data identifiers securely."""
+    def _pad(val):
+        if pd.isna(val) or str(val).strip() in ["", "nan", "NaN"]: return ""
+        s = str(val).split('.')[0].strip()
+        return s.zfill(pad_length) if pad_length else s
+    return series.apply(_pad)
+
+def boolean(series: pd.Series) -> pd.Series:
+    """Maps custom categorical indicator strings cleanly to boolean values."""
+    truth_map = {
+        "y": True, "yes": True, "1": True, "t": True, "true": True,
+        "n": False, "no": False, "0": False, "f": False, "false": False
+    }
+    # Clean the string, lower it, and map it directly to True/False/NaN
+    return series.astype(str).str.strip().str.lower().map(truth_map)
+
+

tidytable/profile/__init__.py

@@ -0,0 +1,9 @@
+from .engine import blueprint, check_anomalies, audit_report, pin_schema, validate
+
+__all__ = [
+    "blueprint",
+    "check_anomalies",
+    "audit_report",
+    "pin_schema",
+    "validate"
+]

tidytable/profile/engine.py

@@ -0,0 +1,62 @@
+import pandas as pd
+import numpy as np
+import json
+
+def blueprint(df: pd.DataFrame) -> dict:
+    """Generates a high-level overview of shapes, data types, and memory metrics."""
+    return {
+        "shape": {"rows": df.shape[0], "columns": df.shape[1]},
+        "dtypes": {str(k): str(v) for k, v in df.dtypes.to_dict().items()},
+        "null_counts": {str(k): int(v) for k, v in df.isna().sum().to_dict().items()}
+    }
+
+def check_anomalies(df: pd.DataFrame) -> list[str]:
+    """Scans boundaries to check for junk placeholder values strings."""
+    alerts = []
+    placeholders = ["?", "n/a", "none", "-", "nan", "null"]
+    
+    for col in df.columns:
+        stringified = df[col].astype(str).str.strip().str.lower()
+        found = stringified[stringified.isin(placeholders)].unique()
+        if len(found) > 0:
+            alerts.append(f"Column '{col}' contains unhandled string anomalies: {list(found)}")
+            
+    return alerts
+
+def audit_report(df: pd.DataFrame, output: str = "cli") -> str:
+    """Compiles a text summary documenting pipeline modifications."""
+    bp = blueprint(df)
+    report = f"=== TIDYTABLE DATA CLEANING AUDIT REPORT ===\n"
+    report += f"Final Dimensions: {bp['shape']['rows']} rows x {bp['shape']['columns']} columns\n"
+    report += f"Column Composition and Null Status Logs:\n"
+    for col, dtype in bp['dtypes'].items():
+        report += f" - {col} ({dtype}): Missing values: {bp['null_counts'][col]}\n"
+    return report
+
+def pin_schema(df: pd.DataFrame, path: str) -> None:
+    """Saves the data structure blueprint to a local template file."""
+    bp = blueprint(df)
+    with open(path, 'w') as f:
+        json.dump(bp, f, indent=4)
+
+def validate(df: pd.DataFrame, schema_path: str) -> bool:
+    """Validates the processed dataset against a saved reference blueprint."""
+    with open(schema_path, 'r') as f:
+        saved_schema = json.load(f)
+        
+    current_cols = set(df.columns)
+    saved_cols = set(saved_schema["dtypes"].keys())
+    
+    if current_cols != saved_cols:
+        missing = saved_cols - current_cols
+        extra = current_cols - saved_cols
+        raise ValueError(f"Schema mismatch. Missing expected columns: {missing}. Unexpected extra columns: {extra}")
+        
+    for col in df.columns:
+        curr_type = str(df[col].dtype)
+        saved_type = saved_schema["dtypes"][col]
+        # Allow flexible evaluation comparisons for strings/objects object mappings
+        if curr_type != saved_type and not (curr_type == "object" and saved_type == "string"):
+            raise TypeError(f"Type validation alert on '{col}': Expected {saved_type}, found {curr_type}")
+            
+    return True

tidytable/reconcile/__init__.py

@@ -0,0 +1,6 @@
+from .engine import sheet_diff, align_schemas
+
+__all__ = [
+    "sheet_diff",
+    "align_schemas"
+]

tidytable/reconcile/engine.py

@@ -0,0 +1,38 @@
+import pandas as pd
+
+def sheet_diff(df_old: pd.DataFrame, df_new: pd.DataFrame, key_column: str) -> dict[str, pd.DataFrame]:
+    """Compares two balance frames to extract record additions, deletions, and alterations."""
+    old_idx = df_old.set_index(key_column)
+    new_idx = df_new.set_index(key_column)
+    
+    added_keys = new_idx.index.difference(old_idx.index)
+    dropped_keys = old_idx.index.difference(new_idx.index)
+    shared_keys = old_idx.index.intersection(new_idx.index)
+    
+    added_df = new_idx.loc[added_keys].reset_index()
+    dropped_df = old_idx.loc[dropped_keys].reset_index()
+    
+    # Identify modified value items
+    modified_rows = []
+    for key in shared_keys:
+        old_row = old_idx.loc[key]
+        new_row = new_idx.loc[key]
+        if not old_row.equals(new_row):
+            diff_mask = old_row != new_row
+            row_data = {key_column: key}
+            for col in old_idx.columns:
+                if diff_mask.get(col, False):
+                    row_data[f"{col}_old"] = old_row[col]
+                    row_data[f"{col}_new"] = new_row[col]
+            modified_rows.append(row_data)
+            
+    return {
+        "Added": added_df,
+        "Dropped": dropped_df,
+        "Modified": pd.DataFrame(modified_rows)
+    }
+
+def align_schemas(df_old: pd.DataFrame, df_new: pd.DataFrame) -> tuple[pd.DataFrame, pd.DataFrame]:
+    """Re-orders and aligns column structures between two file generations."""
+    shared_cols = [col for col in df_old.columns if col in df_new.columns]
+    return df_old[shared_cols].copy(), df_new[shared_cols].copy()

tidytable/structural/__init__.py

@@ -0,0 +1,7 @@
+from .engine import rename_columns, strip_whitespace, standardize_categories
+
+__all__ = [
+    "rename_columns",
+    "strip_whitespace",
+    "standardize_categories"
+]

tidytable/structural/engine.py

@@ -0,0 +1,44 @@
+import pandas as pd
+import re
+from rapidfuzz import process, utils
+
+def rename_columns(df: pd.DataFrame, style: str = "snake_case") -> pd.DataFrame:
+    """Converts column labels cleanly into standardized variable formats."""
+    cleaned_df = df.copy()
+    new_names = []
+    
+    for col in cleaned_df.columns:
+        s = str(col).strip()
+        if style == "snake_case":
+            s = re.sub(r'[^\w\s-]', '', s)  # Drop punctuation marks
+            s = s.replace('-', '_')         # Convert hard dashes to clear underscores
+            s = re.sub(r'[\s_]+', '_', s)   # Collapse space/underscore variations
+            s = s.strip('_').lower()        # Trim edges and lowercase
+        new_names.append(s)
+        
+    cleaned_df.columns = new_names
+    return cleaned_df
+
+def strip_whitespace(series: pd.Series) -> pd.Series:
+    """Strips regular spaces, tab lines, and hidden web code spaces (\xa0)."""
+    return series.astype(str).apply(lambda x: re.sub(r'\s+', ' ', x).strip() if pd.notna(x) else x)
+
+def standardize_categories(series: pd.Series, mapping: dict = None, auto_cluster: bool = False) -> pd.Series:
+    """Groups scattered spelling variations or mapping targets into a clean key frame."""
+    s = series.copy()
+    if mapping:
+        reverse_map = {variant: key for key, list_var in mapping.items() for variant in list_var}
+        return s.apply(lambda x: reverse_map.get(str(x).strip(), x))
+        
+    if auto_cluster:
+        unique_vals = [str(v).strip() for v in s.dropna().unique()]
+        processed_map = {}
+        # Simple clustering matrix setup
+        for val in unique_vals:
+            if val in processed_map: continue
+            matches = process.extract(val, unique_vals, score_cutoff=85.0)
+            for match in matches:
+                processed_map[match[0]] = val
+        return s.apply(lambda x: processed_map.get(str(x).strip(), x) if pd.notna(x) else x)
+        
+    return s

tidytable/xl/__init__.py

@@ -0,0 +1,8 @@
+from .engine import load_workbook, unmerge_and_fill, sniff_headers, split_multi_tables
+
+__all__ = [
+    "load_workbook",
+    "unmerge_and_fill",
+    "sniff_headers",
+    "split_multi_tables"
+]

tidytable/xl/engine.py

@@ -0,0 +1,56 @@
+import pandas as pd
+import numpy as np
+import openpyxl
+
+def load_workbook(file_path: str) -> dict[str, pd.DataFrame]:
+    """Loads an Excel file and returns a dictionary of dataframes mapped by sheet names."""
+    return pd.read_excel(file_path, sheet_name=None)
+
+def unmerge_and_fill(sheet_data: pd.DataFrame, strategy: str = "ffill") -> pd.DataFrame:
+    """Detects merged cells layout defects and flattens values forward or laterally."""
+    df = sheet_data.copy()
+    if strategy == "ffill":
+        return df.ffill()
+    elif strategy == "lfill":
+        return df.ffill(axis=1)
+    else:
+        raise ValueError("Strategy must be either 'ffill' or 'lfill'")
+
+def sniff_headers(sheet_data: pd.DataFrame, scan_rows: int = 20) -> tuple[int, list[str]]:
+    """Locates where metadata panels clear out and structured headers begin."""
+    df_scan = sheet_data.head(scan_rows)
+    best_row_idx = 0
+    max_non_nulls = -1
+    
+    for idx, row in df_scan.iterrows():
+        non_null_count = row.notna().sum()
+        if non_null_count > max_non_nulls:
+            max_non_nulls = non_null_count
+            best_row_idx = idx
+            
+    detected_headers = [str(val).strip() for val in sheet_data.iloc[best_row_idx].tolist()]
+    return int(best_row_idx), detected_headers
+
+def split_multi_tables(sheet_data: pd.DataFrame) -> list[pd.DataFrame]:
+    """Slices a single layout matrix into distinct data tables if isolated by full empty spaces."""
+    empty_cols = sheet_data.isna().all(axis=0)
+    split_indices = np.where(empty_cols)[0]
+    
+    if len(split_indices) == 0:
+        return [sheet_data]
+        
+    tables = []
+    start_col = 0
+    for idx in split_indices:
+        if idx > start_col:
+            slice_df = sheet_data.iloc[:, start_col:idx].dropna(how='all')
+            if not slice_df.empty:
+                tables.append(slice_df.reset_index(drop=True))
+        start_col = idx + 1
+        
+    if start_col < sheet_data.shape[1]:
+        slice_df = sheet_data.iloc[:, start_col:].dropna(how='all')
+        if not slice_df.empty:
+            tables.append(slice_df.reset_index(drop=True))
+            
+    return tables

tidytable_core-1.0.0.dist-info/METADATA

@@ -0,0 +1,330 @@
+Metadata-Version: 2.4
+Name: tidytable-core
+Version: 1.0.0
+Summary: An ecosystem-style explicit data cleaning framework for Excel and CSV pipelines.
+Author-email: Aayush Vijay <aayushvj8699@gmail.com>
+Project-URL: Homepage, https://github.com/aayushvijay/tidytable
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: rapidfuzz>=3.0.0
+Dynamic: license-file
+
+Here is the raw Markdown block. You can copy everything inside this block and paste it directly into your `README.md` file:
+
+```markdown
+# tidytable-core 🧹
+
+An ecosystem-style, explicit data cleaning framework built for data analysts who bridge the gap between messy, human-formatted Excel/CSV spreadsheets and production-ready Python data structures.
+
+Unlike "black-box" cleaning scripts that automatically change your underlying values, `tidytable` forces an **explicit pipeline paradigm**. Each transformation engine is completely decoupled, granting you absolute control and step-by-step data lineage tracking.
+
+---
+
+## 🚀 Installation & System Configuration
+
+Install `tidytable-core` globally from the Python Package Index (PyPI):
+
+```bash
+pip install tidytable-core
+
+```
+
+### Core External System Dependencies
+
+* **`pandas`**: Core tabular dataframe manipulation engine.
+* **`openpyxl`**: Memory-mapped engine for modern `.xlsx` workbook streams.
+* **`python-dateutil`**: Dynamic flexible timestamp text resolution matrix parser.
+* **`rapidfuzz`**: High-performance Levenshtein Distance string similarity evaluation index engine.
+
+---
+
+## 🏗️ Architectural Execution Pipeline
+
+Data flows sequentially through your explicitly invoked processing domains:
+
+```
+[ Messy Spreadsheet File ]
+            │
+            ▼
+┌───────────────────────┐
+│     tidytable.xl      │ ──► Resolves unaligned human-formatted layout grids.
+└───────────┬───────────┘
+            │ (Tabular Data Stream)
+            ▼
+┌───────────────────────┐
+│  tidytable.structural │ ──► Standardizes variable labels and strips whitespace.
+└───────────┬───────────┘
+            │
+            ▼
+┌───────────────────────┐
+│    tidytable.parse    │ ──► Casts values safely into clean data types.
+└───────────┬───────────┘
+            │
+            ▼
+┌───────────────────────┐
+│   tidytable.missing   │ ──► Drops empty panels and applies imputation profiles.
+└───────────┬───────────┘
+            │
+            ▼
+┌───────────────────────┐
+│    tidytable.dedup    │ ──► Filters duplicate records safely.
+└───────────┬───────────┘
+            │
+            ▼
+┌───────────────────────┐
+│   tidytable.profile   │ ──► Validates constraints and generates audit ledger logs.
+└───────────┬───────────┘
+            │
+            ▼
+  [ Pristine DataFrame ]
+
+```
+
+---
+
+## 📚 Complete Sub-Library Blueprint Reference
+
+### 1. `tidytable.xl` (The Excel Surgeon)
+
+Extracts pristine data grids from visually stylized worksheets.
+
+#### `xl.load_workbook(file_path: str) -> dict[str, pd.DataFrame]`
+
+* **Use**: Loads an entire workbook into memory.
+* **Arguments**: `file_path` (*str*): System destination path pointing to an Excel document.
+
+#### `xl.unmerge_and_fill(sheet_data: pd.DataFrame, strategy: str = "ffill") -> pd.DataFrame`
+
+* **Use**: Flattens merged cells and fills empty fields down or across so rows stay linked.
+* **Arguments**:
+* `sheet_data` (*DataFrame*): The input sheet table matrix.
+* `strategy` (*str*): Direction constraint rule. `"ffill"` (forward fill down) or `"lfill"` (lateral fill across).
+
+
+
+#### `xl.sniff_headers(sheet_data: pd.DataFrame, scan_rows: int = 20) -> tuple[int, list[str]]`
+
+* **Use**: Skips title banners and KPI cards to find where the actual table headers start.
+* **Arguments**: `scan_rows` (*int*): Search depth row index limit.
+
+```python
+import tidytable as tt
+
+sheets = tt.xl.load_workbook("sales_report.xlsx")
+raw_data = sheets["Q2_Leads"]
+
+# Sniff header index location and clean names
+header_idx, headers = tt.xl.sniff_headers(raw_data, scan_rows=15)
+
+# Unmerge and prop values down to form a database structure
+df = tt.xl.unmerge_and_fill(raw_data, strategy="ffill")
+
+```
+
+---
+
+### 2. `tidytable.structural` (The Text Blacksmith)
+
+Cleans and standardizes column structures and text anomalies.
+
+#### `structural.rename_columns(df: pd.DataFrame, style: str = "snake_case") -> pd.DataFrame`
+
+* **Use**: Converts columns (like `"Gross Profit (%)"`) into clean variables (`"gross_profit"`).
+* **Arguments**: `style` (*str*): Re-casing format rules. Default is `"snake_case"`.
+
+#### `structural.strip_whitespace(series: pd.Series) -> pd.Series`
+
+* **Use**: Deep-strips leading/trailing spaces, tab breaks, and hidden non-breaking spaces (`\xa0`).
+
+#### `structural.standardize_categories(series: pd.Series, mapping: dict = None, auto_cluster: bool = False) -> pd.Series`
+
+* **Use**: Groups manual typos and naming variations into a single target category name.
+* **Arguments**:
+* `mapping` (*dict*): Manual dictionary rules map (e.g., `{"USA": ["usa", "U.S.A.", "us"]}`).
+* `auto_cluster` (*bool*): Uses Levenshtein Distance to merge variations automatically.
+
+
+
+```python
+df = tt.structural.rename_columns(df, style="snake_case")
+df["product_name"] = tt.structural.strip_whitespace(df["product_name"])
+
+# Merge regional text typos automatically using string distance clustering
+df["region"] = tt.structural.standardize_categories(df["region"], auto_cluster=True)
+
+```
+
+---
+
+### 3. `tidytable.parse` (The Type Whisperer)
+
+Converts raw string text blocks into strict mathematical datatypes without crashing.
+
+#### `parse.dates(series: pd.Series, dayfirst: bool = False) -> pd.Series`
+
+* **Use**: Parses mixed date format variations in a single column into uniform ISO datetimes.
+
+#### `parse.financials(series: pd.Series) -> pd.Series`
+
+* **Use**: Extracts numeric values from accounting styles like `"$ (1,250.00)"` or `"12K"`.
+
+#### `parse.repair_identifiers(series: pd.Series, pad_length: int = None) -> pd.Series`
+
+* **Use**: Restores dropped leading zeroes on data codes (e.g., converts float `401.0` back to `"00401"`).
+
+```python
+df["invoice_date"] = tt.parse.dates(df["invoice_date"], dayfirst=False)
+df["net_revenue"] = tt.parse.financials(df["net_revenue"])
+df["zip_code"] = tt.parse.repair_identifiers(df["zip_code"], pad_length=5)
+df["roi_metric"] = tt.parse.handle_formula_ghosts(df["roi_metric"], error_strategy="coerce")
+
+```
+
+---
+
+### 4. `tidytable.missing` (The Ghost Hunter)
+
+Identifies and resolves gaps in data matrices.
+
+#### `missing.drop_empty_cols(df: pd.DataFrame, threshold: float = 0.50) -> pd.DataFrame`
+
+* **Use**: Drops column attributes where the missing values ratio exceeds the threshold boundary limit.
+
+#### `missing.flag_absence(df: pd.DataFrame, columns: list[str]) -> pd.DataFrame`
+
+* **Use**: Appends a binary companion indicator column (`{column}_is_missing`) to keep the data signal before running imputation.
+
+#### `missing.impute(series: pd.Series, strategy: str = "median") -> pd.Series`
+
+* **Use**: Fills null voids based on chosen statistical parameters (`"mean"`, `"median"`, `"mode"`).
+
+```python
+df = tt.missing.drop_empty_cols(df, threshold=0.40)
+df = tt.missing.flag_absence(df, columns=["customer_age"])
+df["customer_age"] = tt.missing.impute(df["customer_age"], strategy="median")
+
+```
+
+---
+
+### 5. `tidytable.dedup` (The Twin Eliminator)
+
+Detects and drops duplicate entries across your rows.
+
+#### `dedup.absolute(df: pd.DataFrame) -> pd.DataFrame`
+
+* **Use**: Drops rows only if they match exactly across every single field.
+
+#### `dedup.partial(df: pd.DataFrame, subset: list[str], keep: str = "latest", timestamp_col: str = None) -> pd.DataFrame`
+
+* **Use**: Resolves record updates by keeping the earliest or latest transaction entry for a unique key.
+
+```python
+# Clear absolute identical rows
+df = tt.dedup.absolute(df)
+
+# For matching customer IDs, keep only the record with the most recent update timestamp
+df = tt.dedup.partial(df, subset=["customer_id"], keep="latest", timestamp_col="updated_at")
+
+```
+
+---
+
+### 6. `tidytable.merge` (The VLOOKUP Bridge)
+
+Joins separate files together even when keys are messy, incomplete, or slightly misspelled.
+
+```python
+# Identify mismatched elements before executing joins
+pre_flight = tt.merge.join_diagnose(left_df=leads_df, right_df=master_df, left_on="vendor", right_on="v_name")
+
+# Join matching rows even if there are typos (e.g., matches "Apple Inc." to "Apple, Inc.")
+joined_df = tt.merge.fuzzy_vlookup(leads_df, master_df, left_on="vendor", right_on="v_name", threshold=0.88)
+
+```
+
+---
+
+### 7. `tidytable.reconcile` (The Ledger Auditor)
+
+Automates version control checks between separate instances of the same file structure.
+
+```python
+# Generate structural audits comparing January data against February data
+ledger_updates = tt.reconcile.sheet_diff(df_old=jan_df, df_new=feb_df, key_column="transaction_id")
+
+print("New rows added this month:", len(ledger_updates["Added"]))
+print("Row modifications captured:", len(ledger_updates["Modified"]))
+
+```
+
+---
+
+### 8. `tidytable.profile` (The Auditor & Schema Guard)
+
+Handles file schema pinning, anomaly detection, and automated audit trails.
+
+```python
+# Scan for raw strings masking null values (e.g., "?", "n/a", "-")
+anomalies = tt.profile.check_anomalies(df)
+
+# Validate current file structure against last month's blueprint to make sure scripts don't crash
+if tt.profile.validate(df, schema_path="schemas/prod_blueprint.json"):
+    # Output file pipeline performance audit change log metrics
+    print(tt.profile.audit_report(df, output="cli"))
+
+```
+
+---
+
+## 🎯 Complete End-to-End Explicit Analyst Workflow
+
+Here is a complete real-world script showing how an analyst runs a detailed cleaning pipeline manually:
+
+```python
+import tidytable as tt
+import pandas as pd
+
+# Step 1: Layout Normalization
+workbook = tt.xl.load_workbook("raw_factory_data.xlsx")
+sheet_grid = workbook["Master_Log"]
+df = tt.xl.unmerge_and_fill(sheet_grid, strategy="ffill")
+
+# Step 2: Structural Column Cleaning
+df = tt.structural.rename_columns(df, style="snake_case")
+df["part_name"] = tt.structural.strip_whitespace(df["part_name"])
+
+# Step 3: Type Safe Parsing
+df["serial_id"] = tt.parse.repair_identifiers(df["serial_id"], pad_length=6)
+df["cost"] = tt.parse.financials(df["cost"])
+df["log_date"] = tt.parse.dates(df["log_date"])
+
+# Step 4: Integrity and Row Refinement
+df = tt.missing.flag_absence(df, columns=["efficiency_score"])
+df["efficiency_score"] = tt.missing.impute(df["efficiency_score"], strategy="mean")
+df = tt.dedup.absolute(df)
+
+# Step 5: Verification & Schema Pinning
+if tt.profile.validate(df, schema_path="schemas/factory_spec.json"):
+    df.to_csv("clean_factory_data.csv", index=False)
+    print(tt.profile.audit_report(df, output="cli"))
+
+```
+
+---
+
+## ⚖️ License
+
+Distributed under the MIT License. See `LICENSE` for details.
+
+```
+
+```

tidytable_core-1.0.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+tidytable/__init__.py,sha256=OhNae229kC5RbGOwFtVpSzXKpkIuXMTUwBoeFjDQoQk,298
+tidytable/dedup/__init__.py,sha256=d3l94dahpt9698AAEKjD615WsL9FacKYPDGRGIPr2y0,83
+tidytable/dedup/engine.py,sha256=8wiMmQToV7AprEr-siQlBFqxaGl5_hX3xb_9kQCIHx8,896
+tidytable/merge/__init__.py,sha256=BU-Z1T2Zw6U6y-RV5CdznU5VHNgJid4rWJi7H2fHEME,105
+tidytable/merge/engine.py,sha256=0rRRFiEHwIdr8IRmto9II7X9p-ZjQhJ7TMFJhf__MqA,1490
+tidytable/missing/__init__.py,sha256=B33QsEgD_37bwTtTZtKwTf0j0DXg8q5hpxEXgAFQcjg,129
+tidytable/missing/engine.py,sha256=w3pQ0IPpGp0xDEnCz5yiK5bp4OlUw5LMuM24UJNfQlI,1071
+tidytable/parse/__init__.py,sha256=9iGY8AbhVxUnGOpJy0KzNEWypvxamLvtnRhguSrqZ-0,205
+tidytable/parse/engine.py,sha256=73kdQsBGy848FiYiUv1MIFlCu4Z0shgKEPg3wINuxWw,3071
+tidytable/profile/__init__.py,sha256=vD7IOmIGlT8A_WW9AYNuIxuFxIVuPBcdZ0iryx-W9ds,191
+tidytable/profile/engine.py,sha256=r5NRlRmvstii9ZItlqjtzDxritDVxrHnUdFU3jty5gY,2676
+tidytable/reconcile/__init__.py,sha256=k2wQKsrb9WIjBjzIRxDGWn8dlADYC52qqK-dPV8kafw,99
+tidytable/reconcile/engine.py,sha256=ELuE-ByULeIboJ621m9dtsZouQgykdktIpSvIkWC-Vs,1592
+tidytable/structural/__init__.py,sha256=rO4Ed2QkuRFrmbi9S76Cc-_qNAVdSIJbjsvjrlkMDwo,167
+tidytable/structural/engine.py,sha256=n_eTiPa3PZeC1FhR8h5vbpFIl_N5oM33JuiwHavUGvU,1933
+tidytable/xl/__init__.py,sha256=iiuAckb6es9o6ut4f07qBJQzk0VNYeYHlSQtrqmCUqQ,193
+tidytable/xl/engine.py,sha256=vNzTYvA8AQk3lirkCCuQnOIF6QH1c4jdBfPIORsFVp0,2148
+tidytable_core-1.0.0.dist-info/licenses/LICENSE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tidytable_core-1.0.0.dist-info/METADATA,sha256=ZMT4TnhoQwx_1IgW9GXViSDimzDL6fZm6JFtE91-mu0,11828
+tidytable_core-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+tidytable_core-1.0.0.dist-info/top_level.txt,sha256=DYeHvMlVFQwgpGUmlMe26iZrkoha6of6-nkB3B5vMg0,10
+tidytable_core-1.0.0.dist-info/RECORD,,

tidytable_core-1.0.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
+

tidytable_core-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tidytable