json-extract-pandas 0.1.0__tar.gz

json_extract_pandas-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

json_extract_pandas-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: json-extract-pandas
+Version: 0.1.0
+Summary: A robust JSON-to-CSV extraction engine for deeply nested payloads.
+Author-email: Vatsa <228140210+svr-s@users.noreply.github.com>
+Project-URL: Homepage, https://github.com/svr-s/json_extract
+Project-URL: Issues, https://github.com/svr-s/json_extract/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.0.0
+Dynamic: license-file
+
+# JSON Extract (`json_extract`)
+
+A high-performance, reusable Python utility designed to natively flatten, parse, and filter deeply nested JSON data into clean, normalized Pandas DataFrames. It acts as a powerful JSON-to-CSV extraction engine for robust data pipelines.
+
+## Features
+- **Deep Hierarchical Flattening**: Uses recursive logic to safely flatten any nested JSON object, preserving exact path context via dot-notation (e.g. `parent.child.property`).
+- **Cartesian List Explosion**: Intelligently handles embedded lists/arrays, exploding them into new rows to prevent data loss or complex column bloat.
+- **Dynamic Filtering**: Robust API to slice your exact dataset out of massive payloads.
+  - *Column Filtering*: Strict matching, 1-based numeric indexing (e.g., `["1-7", 10]`), Prefix wildcards (`parent.*`), and Suffix wildcards (`*.statusCode`).
+  - *Row Filtering*: Filter rows by exact values or lists of acceptable values.
+- **Smart Data Cleaning**: Natively deduplicate rows, drop `NaN`/blanks, and cleanly simplify column headers without causing naming collisions.
+- **Self-Documenting Metadata**: Instantly returns schema and dimension metadata (`table_size`, `column_names` mapped by 1-based index) alongside the DataFrame.
+
+## Requirements
+- Python 3.9+
+- `pandas`
+
+---
+
+## Installation & Usage
+
+Import `extract_json` directly into your data pipeline script:
+
+```python
+import json
+from json_extract import extract_json
+
+# 1. Load your raw payload
+with open('data.json', 'r') as f:
+    payload = json.load(f)
+
+# 2. Extract!
+meta, df = extract_json(payload)
+print(df.head())
+```
+
+---
+
+## Function Reference
+
+### `extract_json(json_data, **kwargs)`
+
+The primary extraction engine.
+
+#### Parameters
+
+* **`json_data`** `(dict | list)`: **(Required)**
+  The parsed JSON payload to process. It handles normal dictionaries, lists of dictionaries, or even raw primitive 2D arrays (`[[0, 1], [2, 3]]`) mapping them securely to `col1`, `col2`.
+
+* **`desired_columns`** `(list)`: *(Optional)*
+  A list of specific column names or numeric indices to retain. It natively supports numeric ranges and Unix-style wildcards (`*`, `?`).
+  * **Numeric Ranges/Indices (1-based)**: `["1-7", "10", 12]` (Gets columns 1 through 7, 10, and 12). Duplicate overlaps are safely ignored.
+  * **Exact Match**: `["accountId"]`
+  * **Prefix Wildcard**: `["shippingAddress.*"]` (Gets all properties starting with `shippingAddress.`)
+  * **Suffix Wildcard**: `["*.statusCode"]` (Gets every `statusCode` across the entire document)
+
+* **`row_filters`** `(dict)`: *(Optional)*
+  A dictionary mapping a specific column to a required value. You can supply a single exact match, or a list of matches.
+  * **Exact**: `{"accountId": "ACC-99823-XYZ"}`
+  * **List**: `{"regionCode": ["US-EAST", "EU-WEST"]}`
+
+* **`remove_duplicates`** `(bool)`: *(Optional, Default: False)*
+  If `True`, drops any completely identical rows generated from Cartesian explosions after all filters are applied.
+
+* **`simplify_columns`** `(bool)`: *(Optional, Default: False)*
+  If `True`, it trims away verbose parent hierarchies in the column names, leaving only the final child key (e.g., `parent.child.shortName` safely becomes `shortName`). 
+  *Note: If simplifying causes a name collision (e.g., `type.code` and `name.code` both mapping to `code`), it intelligently retains the full dot-notation for those specific columns to prevent data overwrite.*
+
+* **`remove_empty`** `(bool | str)`: *(Optional, Default: False)*
+  Cleans the dataset by dropping rows polluted with missing values (`NaN`, `None`) or blank strings (`""`).
+  * `'any'` (or `True`): Strict. Drops the row if *any* of the filtered columns are missing.
+  * `'all'`: Lenient. Drops the row only if *all* of the filtered columns are entirely missing.
+  * `False`: Disabled. Retains everything.
+
+---
+
+## Full Example Pipeline
+
+Here is an example demonstrating all parameters functioning in tandem to slice a massive, nested payload down to an exact, clean specification:
+
+```python
+import json
+from json_extract import extract_json
+
+with open('users_export.json', 'r') as f:
+    data = json.load(f)
+
+# Extract only the fields we care about, exactly for our target accounts
+meta, df = extract_json(
+    json_data=data,
+    
+    # 1. Grab Account ID, specific columns by index, and shipping address properties
+    desired_columns=[
+        "accountId", 
+        "2-4",
+        "shippingAddress.*",
+        "*.statusCode"
+    ],
+    
+    # 2. Filter to just these two specific regions
+    row_filters={
+        "regionCode": ["US-EAST", "EU-WEST"]
+    },
+    
+    # 3. Clean up the resulting DataFrame
+    remove_duplicates=True,
+    simplify_columns=True,  # Turns "shippingAddress.zipCode" into "zipCode"
+    remove_empty='all'      # Drop rows that are totally blank
+)
+
+print(df.to_csv(index=False))
+```

json_extract_pandas-0.1.0/README.md

@@ -0,0 +1,112 @@
+# JSON Extract (`json_extract`)
+
+A high-performance, reusable Python utility designed to natively flatten, parse, and filter deeply nested JSON data into clean, normalized Pandas DataFrames. It acts as a powerful JSON-to-CSV extraction engine for robust data pipelines.
+
+## Features
+- **Deep Hierarchical Flattening**: Uses recursive logic to safely flatten any nested JSON object, preserving exact path context via dot-notation (e.g. `parent.child.property`).
+- **Cartesian List Explosion**: Intelligently handles embedded lists/arrays, exploding them into new rows to prevent data loss or complex column bloat.
+- **Dynamic Filtering**: Robust API to slice your exact dataset out of massive payloads.
+  - *Column Filtering*: Strict matching, 1-based numeric indexing (e.g., `["1-7", 10]`), Prefix wildcards (`parent.*`), and Suffix wildcards (`*.statusCode`).
+  - *Row Filtering*: Filter rows by exact values or lists of acceptable values.
+- **Smart Data Cleaning**: Natively deduplicate rows, drop `NaN`/blanks, and cleanly simplify column headers without causing naming collisions.
+- **Self-Documenting Metadata**: Instantly returns schema and dimension metadata (`table_size`, `column_names` mapped by 1-based index) alongside the DataFrame.
+
+## Requirements
+- Python 3.9+
+- `pandas`
+
+---
+
+## Installation & Usage
+
+Import `extract_json` directly into your data pipeline script:
+
+```python
+import json
+from json_extract import extract_json
+
+# 1. Load your raw payload
+with open('data.json', 'r') as f:
+    payload = json.load(f)
+
+# 2. Extract!
+meta, df = extract_json(payload)
+print(df.head())
+```
+
+---
+
+## Function Reference
+
+### `extract_json(json_data, **kwargs)`
+
+The primary extraction engine.
+
+#### Parameters
+
+* **`json_data`** `(dict | list)`: **(Required)**
+  The parsed JSON payload to process. It handles normal dictionaries, lists of dictionaries, or even raw primitive 2D arrays (`[[0, 1], [2, 3]]`) mapping them securely to `col1`, `col2`.
+
+* **`desired_columns`** `(list)`: *(Optional)*
+  A list of specific column names or numeric indices to retain. It natively supports numeric ranges and Unix-style wildcards (`*`, `?`).
+  * **Numeric Ranges/Indices (1-based)**: `["1-7", "10", 12]` (Gets columns 1 through 7, 10, and 12). Duplicate overlaps are safely ignored.
+  * **Exact Match**: `["accountId"]`
+  * **Prefix Wildcard**: `["shippingAddress.*"]` (Gets all properties starting with `shippingAddress.`)
+  * **Suffix Wildcard**: `["*.statusCode"]` (Gets every `statusCode` across the entire document)
+
+* **`row_filters`** `(dict)`: *(Optional)*
+  A dictionary mapping a specific column to a required value. You can supply a single exact match, or a list of matches.
+  * **Exact**: `{"accountId": "ACC-99823-XYZ"}`
+  * **List**: `{"regionCode": ["US-EAST", "EU-WEST"]}`
+
+* **`remove_duplicates`** `(bool)`: *(Optional, Default: False)*
+  If `True`, drops any completely identical rows generated from Cartesian explosions after all filters are applied.
+
+* **`simplify_columns`** `(bool)`: *(Optional, Default: False)*
+  If `True`, it trims away verbose parent hierarchies in the column names, leaving only the final child key (e.g., `parent.child.shortName` safely becomes `shortName`). 
+  *Note: If simplifying causes a name collision (e.g., `type.code` and `name.code` both mapping to `code`), it intelligently retains the full dot-notation for those specific columns to prevent data overwrite.*
+
+* **`remove_empty`** `(bool | str)`: *(Optional, Default: False)*
+  Cleans the dataset by dropping rows polluted with missing values (`NaN`, `None`) or blank strings (`""`).
+  * `'any'` (or `True`): Strict. Drops the row if *any* of the filtered columns are missing.
+  * `'all'`: Lenient. Drops the row only if *all* of the filtered columns are entirely missing.
+  * `False`: Disabled. Retains everything.
+
+---
+
+## Full Example Pipeline
+
+Here is an example demonstrating all parameters functioning in tandem to slice a massive, nested payload down to an exact, clean specification:
+
+```python
+import json
+from json_extract import extract_json
+
+with open('users_export.json', 'r') as f:
+    data = json.load(f)
+
+# Extract only the fields we care about, exactly for our target accounts
+meta, df = extract_json(
+    json_data=data,
+    
+    # 1. Grab Account ID, specific columns by index, and shipping address properties
+    desired_columns=[
+        "accountId", 
+        "2-4",
+        "shippingAddress.*",
+        "*.statusCode"
+    ],
+    
+    # 2. Filter to just these two specific regions
+    row_filters={
+        "regionCode": ["US-EAST", "EU-WEST"]
+    },
+    
+    # 3. Clean up the resulting DataFrame
+    remove_duplicates=True,
+    simplify_columns=True,  # Turns "shippingAddress.zipCode" into "zipCode"
+    remove_empty='all'      # Drop rows that are totally blank
+)
+
+print(df.to_csv(index=False))
+```

json_extract_pandas-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "json-extract-pandas"
+version = "0.1.0"
+authors = [
+  { name="Vatsa", email="228140210+svr-s@users.noreply.github.com" },
+]
+description = "A robust JSON-to-CSV extraction engine for deeply nested payloads."
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "pandas>=1.0.0"
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.urls]
+Homepage = "https://github.com/svr-s/json_extract"
+Issues = "https://github.com/svr-s/json_extract/issues"

json_extract_pandas-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

json_extract_pandas-0.1.0/src/json_extract/__init__.py

@@ -0,0 +1,4 @@
+from .json_extract import extract_json, _flatten_and_expand
+
+__version__ = "0.1.0"
+__all__ = ["extract_json", "_flatten_and_expand"]

json_extract_pandas-0.1.0/src/json_extract/json_extract.py

@@ -0,0 +1,302 @@
+import pandas as pd
+import itertools
+import fnmatch
+import re
+from typing import Union, Optional, Tuple, Dict, Any
+
+def _flatten_and_expand(data, parent_key=''):
+    """
+    Recursively flattens a nested dictionary or list and explodes lists 
+    into multiple rows via Cartesian product.
+    Nested keys are separated by a dot (.).
+    For example: parentEntity.ChildEntity1.SubEntity2
+    """
+    if isinstance(data, dict):
+        key_results = []
+        for k, v in data.items():
+            new_key = f"{parent_key}.{k}" if parent_key else k
+            res = _flatten_and_expand(v, new_key)
+            key_results.append(res)
+            
+        combined_rows = []
+        for combination in itertools.product(*key_results):
+            merged = {}
+            for d in combination:
+                merged.update(d)
+            combined_rows.append(merged)
+            
+        return combined_rows if combined_rows else [{}]
+        
+    elif isinstance(data, list):
+        if not data:
+            return [{parent_key: None}]
+            
+        all_rows = []
+        for item in data:
+            res = _flatten_and_expand(item, parent_key)
+            all_rows.extend(res)
+        return all_rows
+        
+    else:
+        # Base case: primitive value
+        return [{parent_key: data}]
+
+def extract_json(
+    json_data: Union[Dict, list], 
+    desired_columns: Optional[list] = None, 
+    row_filters: Optional[Dict[str, Any]] = None, 
+    remove_duplicates: bool = False, 
+    simplify_columns: bool = False, 
+    remove_empty: Union[bool, str] = False
+) -> Tuple[Dict[str, Any], pd.DataFrame]:
+    """
+    Takes parsed JSON data, extracts the primary records, flattens deeply nested 
+    hierarchies into a pandas DataFrame using dot-notation, and explodes lists 
+    via Cartesian product.
+    
+    This function acts as a robust JSON-to-CSV data extraction engine, specifically
+    built to handle complex, heavily-nested JSON payloads. It automatically gracefully 
+    handles raw primitive arrays, standardizes column names, and allows for powerful 
+    wildcard column extraction and list-based row filtering.
+    
+    Args:
+        json_data (dict | list): 
+            The parsed JSON structure to explode. 
+            Can be a deeply nested dictionary, a list of dictionaries, or even a 
+            raw 2D array (e.g., `[[0, 1], [2, 3]]`) which will be automatically 
+            mapped to `col1`, `col2`, etc.
+            
+        desired_columns (list, optional): 
+            A list of column names, indices, or wildcards to retain in the final DataFrame.
+            - Example (Exact): `["accountId", "user.profile.firstName"]`
+            - Example (Index): `["5", 5]` (Extracts exactly the 5th column, 1-indexed)
+            - Example (Range): `["1-7"]` (Extracts columns 1 through 7 inclusive)
+            - Example (Prefix Wildcard): `["shippingAddress.*"]`
+            - Example (Suffix Wildcard): `["*.statusCode"]`
+            If indices are used alongside other matches that result in duplicates (e.g., `["5", "1-7"]`), 
+            the final columns are safely deduplicated.
+            If a requested column or wildcard matches no columns, a warning is printed.
+            
+        row_filters (dict, optional): 
+            A dictionary mapping column names to desired values to filter the dataset.
+            Values can be a single exact match or a list of acceptable matches.
+            - Example (Exact Match): `{"accountId": "ACC-99823-XYZ"}`
+            - Example (List Match): `{"regionCode": ["US-EAST", "EU-WEST"]}`
+            
+        remove_duplicates (bool, optional): 
+            If True, removes completely identical rows from the final DataFrame 
+            after all filtering has been applied. Defaults to False.
+            
+        simplify_columns (bool, optional): 
+            If True, intelligently strips parent prefixes from column names, retaining 
+            only the final child property (e.g., `parent.child.shortName` becomes `shortName`).
+            If doing so would result in duplicate column names (e.g., both `a.code` and `b.code` 
+            become `code`), it safely preserves their full dot-notation names to prevent collisions.
+            Defaults to False.
+            
+        remove_empty (bool | str, optional): 
+            Cleans the dataset by dropping rows containing missing values (`NaN`, `None`) 
+            or completely empty strings (`""`, `"   "`).
+            - `'any'` (or True): Drops the row if *any* of its filtered columns are missing.
+            - `'all'`: Drops the row only if *all* of its filtered columns are missing.
+            - False: Disables empty row removal. Defaults to False.
+    
+    Returns:
+        tuple: A tuple containing:
+            - meta_data_dict (dict): A dictionary describing the resulting table size 
+              and the exact schema/column names generated. The `column_names` key contains 
+              a dictionary mapping the 1-based numerical index to the respective column name 
+              (e.g., `{1: "accountId", 2: "user.profile.firstName"}`).
+            - pandas_dataframe (pd.DataFrame): The fully flattened, filtered, and 
+              cleaned pandas DataFrame.
+              
+    Raises:
+        ValueError: If `json_data` is not a dict or list, or if parameter types are invalid.
+        KeyError: If an exact column requested in `desired_columns` or `row_filters` 
+                  does not exist in the dataset.
+    """
+    if not isinstance(json_data, (dict, list)):
+        raise ValueError(f"Invalid input: json_data must be a dictionary or a list, got {type(json_data).__name__}.")
+        
+    # 1. Determine the records to process
+    if isinstance(json_data, list):
+        records = json_data
+    elif isinstance(json_data, dict):
+        # Look for keys that contain lists of dictionaries
+        list_keys = [k for k, v in json_data.items() if isinstance(v, list) and len(v) > 0 and isinstance(v[0], dict)]
+        if list_keys:
+            # Pick the key with the largest list, assuming that's the primary data payload
+            largest_list_key = max(list_keys, key=lambda k: len(json_data[k]))
+            records = json_data[largest_list_key]
+        else:
+            # Otherwise, treat the entire dictionary as a single record
+            records = [json_data]
+    else:
+        records = [{"value": json_data}]
+        
+    # Format records if they are raw lists (e.g., CSV-like JSON [[0, 1], [2, 3]])
+    formatted_records = []
+    for r in records:
+        if isinstance(r, list):
+            formatted_records.append({f"col{i+1}": val for i, val in enumerate(r)})
+        else:
+            formatted_records.append(r)
+    records = formatted_records
+        
+    # Flatten and explode each record
+    flattened_records = []
+    for record in records:
+        flattened_records.extend(_flatten_and_expand(record))
+    
+    # Create DataFrame
+    df = pd.DataFrame(flattened_records)
+    
+    # Apply Column Filters
+    if desired_columns:
+        if not isinstance(desired_columns, list):
+            raise ValueError("Invalid input: desired_columns must be a list of strings.")
+            
+        valid_columns = []
+        for req_col in desired_columns:
+            req_str = str(req_col).strip()
+            
+            # Check for range pattern (e.g., "1-7")
+            if re.match(r'^\d+-\d+$', req_str):
+                start, end = map(int, req_str.split('-'))
+                start_idx = max(0, start - 1)
+                end_idx = min(len(df.columns), end)
+                matched_cols = list(df.columns[start_idx:end_idx])
+                if not matched_cols:
+                    print(f"Warning: Index range '{req_str}' is entirely out of bounds for the dataset.")
+                valid_columns.extend(matched_cols)
+                
+            # Check for single digit index (e.g., "5" or 5)
+            elif req_str.isdigit():
+                idx = int(req_str) - 1
+                if 0 <= idx < len(df.columns):
+                    valid_columns.append(df.columns[idx])
+                else:
+                    print(f"Warning: Index '{req_str}' is out of bounds for the dataset.")
+                    
+            # Check for wildcards
+            elif '*' in req_str or '?' in req_str:
+                # Use fnmatch to support both prefix.* and *.suffix patterns
+                matched_cols = [c for c in df.columns if fnmatch.fnmatch(c, req_str)]
+                if not matched_cols:
+                    print(f"Warning: Wildcard filter '{req_str}' did not match any columns in the dataset.")
+                valid_columns.extend(matched_cols)
+                
+            # Exact match
+            else:
+                if req_str in df.columns:
+                    valid_columns.append(req_str)
+                else:
+                    raise KeyError(f"Requested column '{req_str}' does not exist in the exploded dataset.")
+                    
+        # Deduplicate the list while preserving order
+        seen = set()
+        final_columns = [x for x in valid_columns if not (x in seen or seen.add(x))]
+        df = df[final_columns]
+        
+    # Apply Row Filters
+    if row_filters:
+        if not isinstance(row_filters, dict):
+            raise ValueError("Invalid input: row_filters must be a dictionary.")
+            
+        for col, val in row_filters.items():
+            if col in df.columns:
+                if isinstance(val, list):
+                    df = df[df[col].isin(val)]
+                else:
+                    df = df[df[col] == val]
+            else:
+                raise KeyError(f"Row filter column '{col}' does not exist in the exploded dataset.")
+                
+    # Remove Duplicates
+    if remove_duplicates:
+        df = df.drop_duplicates().reset_index(drop=True)
+        
+    # Simplify Column Names
+    if simplify_columns:
+        from collections import defaultdict
+        short_to_original = defaultdict(list)
+        
+        for col in df.columns:
+            short_name = col.split('.')[-1]
+            short_to_original[short_name].append(col)
+            
+        rename_map = {}
+        for short_name, originals in short_to_original.items():
+            if len(originals) == 1:
+                # Unique short name, safe to rename
+                rename_map[originals[0]] = short_name
+            # If len > 1, there is a collision, so we do NOT add them to the rename map.
+            # They will naturally retain their full original names.
+            
+        df = df.rename(columns=rename_map)
+        
+    # Remove Empty/Blanks/NaNs
+    if remove_empty:
+        import numpy as np
+        # Convert empty strings or whitespace-only strings to proper NaNs
+        df = df.replace(r'^\s*$', np.nan, regex=True)
+        
+        if isinstance(remove_empty, str) and remove_empty.lower() == 'all':
+            df = df.dropna(how='all')
+        else:
+            df = df.dropna(how='any')
+            
+        df = df.reset_index(drop=True)
+                
+    # Generate Metadata
+    meta_data = {
+        "table_size": {
+            "rows": int(df.shape[0]),
+            "columns": int(df.shape[1])
+        },
+        "column_names": {i + 1: col for i, col in enumerate(df.columns)}
+    }
+    
+    return meta_data, df
+
+if __name__ == '__main__':
+    # Localized test case to verify the function works
+    import json
+    import os
+    
+    current_dir = os.path.dirname(os.path.abspath(__file__))
+    sample_file = os.path.join(current_dir, 'sample_json.json')
+    
+    if os.path.exists(sample_file):
+        print(f"Loading test data from: {sample_file}")
+        with open(sample_file, 'r', encoding='utf-8') as f:
+            data = json.load(f)
+            
+        # Define some filters for testing
+        col_filters = [
+            "languageCode", 
+            "laborAllocationCodes.code", 
+            "sample_test_4.sample_test_4_1"
+        ]
+        r_filters = {
+            "languageCode": "en-CA"
+        }
+        
+        print(f"Applying Column Filters: {col_filters}")
+        print(f"Applying Row Filters: {r_filters}")
+        
+        meta, exploded_df = extract_json(
+            json_data=data, 
+            desired_columns=col_filters, 
+            row_filters=r_filters,
+            simplify_columns=False,
+            remove_empty='all'
+        )
+        
+        print("\n--- Metadata Result ---")
+        print(json.dumps(meta, indent=4))
+        
+        print("\n--- DataFrame Result ---")
+        print(exploded_df)
+    else:
+        print("Please provide a valid JSON file to test.")

json_extract_pandas-0.1.0/src/json_extract_pandas.egg-info/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: json-extract-pandas
+Version: 0.1.0
+Summary: A robust JSON-to-CSV extraction engine for deeply nested payloads.
+Author-email: Vatsa <228140210+svr-s@users.noreply.github.com>
+Project-URL: Homepage, https://github.com/svr-s/json_extract
+Project-URL: Issues, https://github.com/svr-s/json_extract/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.0.0
+Dynamic: license-file
+
+# JSON Extract (`json_extract`)
+
+A high-performance, reusable Python utility designed to natively flatten, parse, and filter deeply nested JSON data into clean, normalized Pandas DataFrames. It acts as a powerful JSON-to-CSV extraction engine for robust data pipelines.
+
+## Features
+- **Deep Hierarchical Flattening**: Uses recursive logic to safely flatten any nested JSON object, preserving exact path context via dot-notation (e.g. `parent.child.property`).
+- **Cartesian List Explosion**: Intelligently handles embedded lists/arrays, exploding them into new rows to prevent data loss or complex column bloat.
+- **Dynamic Filtering**: Robust API to slice your exact dataset out of massive payloads.
+  - *Column Filtering*: Strict matching, 1-based numeric indexing (e.g., `["1-7", 10]`), Prefix wildcards (`parent.*`), and Suffix wildcards (`*.statusCode`).
+  - *Row Filtering*: Filter rows by exact values or lists of acceptable values.
+- **Smart Data Cleaning**: Natively deduplicate rows, drop `NaN`/blanks, and cleanly simplify column headers without causing naming collisions.
+- **Self-Documenting Metadata**: Instantly returns schema and dimension metadata (`table_size`, `column_names` mapped by 1-based index) alongside the DataFrame.
+
+## Requirements
+- Python 3.9+
+- `pandas`
+
+---
+
+## Installation & Usage
+
+Import `extract_json` directly into your data pipeline script:
+
+```python
+import json
+from json_extract import extract_json
+
+# 1. Load your raw payload
+with open('data.json', 'r') as f:
+    payload = json.load(f)
+
+# 2. Extract!
+meta, df = extract_json(payload)
+print(df.head())
+```
+
+---
+
+## Function Reference
+
+### `extract_json(json_data, **kwargs)`
+
+The primary extraction engine.
+
+#### Parameters
+
+* **`json_data`** `(dict | list)`: **(Required)**
+  The parsed JSON payload to process. It handles normal dictionaries, lists of dictionaries, or even raw primitive 2D arrays (`[[0, 1], [2, 3]]`) mapping them securely to `col1`, `col2`.
+
+* **`desired_columns`** `(list)`: *(Optional)*
+  A list of specific column names or numeric indices to retain. It natively supports numeric ranges and Unix-style wildcards (`*`, `?`).
+  * **Numeric Ranges/Indices (1-based)**: `["1-7", "10", 12]` (Gets columns 1 through 7, 10, and 12). Duplicate overlaps are safely ignored.
+  * **Exact Match**: `["accountId"]`
+  * **Prefix Wildcard**: `["shippingAddress.*"]` (Gets all properties starting with `shippingAddress.`)
+  * **Suffix Wildcard**: `["*.statusCode"]` (Gets every `statusCode` across the entire document)
+
+* **`row_filters`** `(dict)`: *(Optional)*
+  A dictionary mapping a specific column to a required value. You can supply a single exact match, or a list of matches.
+  * **Exact**: `{"accountId": "ACC-99823-XYZ"}`
+  * **List**: `{"regionCode": ["US-EAST", "EU-WEST"]}`
+
+* **`remove_duplicates`** `(bool)`: *(Optional, Default: False)*
+  If `True`, drops any completely identical rows generated from Cartesian explosions after all filters are applied.
+
+* **`simplify_columns`** `(bool)`: *(Optional, Default: False)*
+  If `True`, it trims away verbose parent hierarchies in the column names, leaving only the final child key (e.g., `parent.child.shortName` safely becomes `shortName`). 
+  *Note: If simplifying causes a name collision (e.g., `type.code` and `name.code` both mapping to `code`), it intelligently retains the full dot-notation for those specific columns to prevent data overwrite.*
+
+* **`remove_empty`** `(bool | str)`: *(Optional, Default: False)*
+  Cleans the dataset by dropping rows polluted with missing values (`NaN`, `None`) or blank strings (`""`).
+  * `'any'` (or `True`): Strict. Drops the row if *any* of the filtered columns are missing.
+  * `'all'`: Lenient. Drops the row only if *all* of the filtered columns are entirely missing.
+  * `False`: Disabled. Retains everything.
+
+---
+
+## Full Example Pipeline
+
+Here is an example demonstrating all parameters functioning in tandem to slice a massive, nested payload down to an exact, clean specification:
+
+```python
+import json
+from json_extract import extract_json
+
+with open('users_export.json', 'r') as f:
+    data = json.load(f)
+
+# Extract only the fields we care about, exactly for our target accounts
+meta, df = extract_json(
+    json_data=data,
+    
+    # 1. Grab Account ID, specific columns by index, and shipping address properties
+    desired_columns=[
+        "accountId", 
+        "2-4",
+        "shippingAddress.*",
+        "*.statusCode"
+    ],
+    
+    # 2. Filter to just these two specific regions
+    row_filters={
+        "regionCode": ["US-EAST", "EU-WEST"]
+    },
+    
+    # 3. Clean up the resulting DataFrame
+    remove_duplicates=True,
+    simplify_columns=True,  # Turns "shippingAddress.zipCode" into "zipCode"
+    remove_empty='all'      # Drop rows that are totally blank
+)
+
+print(df.to_csv(index=False))
+```

json_extract_pandas-0.1.0/src/json_extract_pandas.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+src/json_extract/__init__.py
+src/json_extract/json_extract.py
+src/json_extract_pandas.egg-info/PKG-INFO
+src/json_extract_pandas.egg-info/SOURCES.txt
+src/json_extract_pandas.egg-info/dependency_links.txt
+src/json_extract_pandas.egg-info/requires.txt
+src/json_extract_pandas.egg-info/top_level.txt

json_extract_pandas-0.1.0/src/json_extract_pandas.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

json_extract_pandas-0.1.0/src/json_extract_pandas.egg-info/requires.txt

@@ -0,0 +1 @@
+pandas>=1.0.0

json_extract_pandas-0.1.0/src/json_extract_pandas.egg-info/top_level.txt

@@ -0,0 +1 @@
+json_extract