jsonunwrap 0.2.0__tar.gz → 0.2.2__tar.gz

jsonunwrap-0.2.2/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: jsonunwrap
+Version: 0.2.2
+Summary: A small python package that unpacks data from a JSON url and converts it into a csv file.
+Author-email: njuedominic <njuemugodominic@gmail.com>
+Project-URL: Homepage, https://github.com/njuedominic/json-unwrap
+Project-URL: Bug Tracker, https://github.com/njuedominic/json-unwrap/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pandas>=2.0.0
+
+# jsonunwrap
+
+**jsonunwrap** is a simple JSON flattening and normalization library.
+
+```python
+>>> import jsonunwrap as ju
+>>> url = "https://dummyjson.com/carts"
+>>> fetchdata = ju.fetch_json(url)
+>>> df = ju.unwrap_data(fetchdata)
+>>> df.columns
+Index(['id', 'user.name', 'hobbies'], dtype='object')
+>>> len(df)
+2
+```
+
+jsonunwrap allows you to deeply normalize complex, semi-structured nested JSON data into clean pandas DataFrames extremely easily.
+
+---
+
+## Installing jsonunwrap
+
+jsonunwrap is available on PyPI:
+
+```bash
+$ python -m pip install jsonunwrap
+```
+
+## Supported Features & Best–Practices
+
+jsonunwrap is ready for the data parsing demands of modern web APIs, automation scripts, and data engineering pipelines.
+
+- Recursive Deep-Flattening (Dot-notation formatting for sub-dictionaries)
+- Automated List Explosion (Spanning embedded primitive lists safely into unique rows)
+- Endpoint Target Binding (Fetch and write stream sequences in a single wrapper)
+- Clean API Namespace (Unified module boundaries with zero complex configuration maps)
+
+---
+
+## Quick Usage Reference
+
+### Download, Normalize, and Export an API Stream to Disk
+
+```python
+import jsonunwrap as ju
+
+target_url = "url"
+output_file = "data/normalized_users.csv"
+
+# Fetch, unwrap nested schemas, and generate a local CSV payload
+df = ju.json_to_csv(target_url, output_file)
+```
+
+---
+
+## Core API Documentation
+
+The complete package interaction map exposes three primary interfaces:
+
+### `jsonunwrap.unwrap_data(data)`
+Recursively flattens an in-memory dictionary or list of records. Returns a parsed `pandas.DataFrame`.
+
+### `jsonunwrap.fetch_json(url, **kwargs)`
+A connection delivery utility utilizing the `requests` transport subsystem. Passes `**kwargs` onwards to target handlers.
+
+### `jsonunwrap.json_to_csv(url, output_path)`
+High-level workflow coordinator connecting remote schema acquisition loops directly to a structural local CSV export.
+
+---
+
+## Contributions & Testing
+
+To test modifications locally or prepare adjustments, execute using `pytest`:
+
+```bash
+\$ git clone https://github.com/njuedominic/json-unwrap
+\$ cd jsonunwrap
+\(python -m pip install -e .[test]\) pytest
+```

jsonunwrap-0.2.2/README.md

@@ -0,0 +1,78 @@
+# jsonunwrap
+
+**jsonunwrap** is a simple JSON flattening and normalization library.
+
+```python
+>>> import jsonunwrap as ju
+>>> url = "https://dummyjson.com/carts"
+>>> fetchdata = ju.fetch_json(url)
+>>> df = ju.unwrap_data(fetchdata)
+>>> df.columns
+Index(['id', 'user.name', 'hobbies'], dtype='object')
+>>> len(df)
+2
+```
+
+jsonunwrap allows you to deeply normalize complex, semi-structured nested JSON data into clean pandas DataFrames extremely easily.
+
+---
+
+## Installing jsonunwrap
+
+jsonunwrap is available on PyPI:
+
+```bash
+$ python -m pip install jsonunwrap
+```
+
+## Supported Features & Best–Practices
+
+jsonunwrap is ready for the data parsing demands of modern web APIs, automation scripts, and data engineering pipelines.
+
+- Recursive Deep-Flattening (Dot-notation formatting for sub-dictionaries)
+- Automated List Explosion (Spanning embedded primitive lists safely into unique rows)
+- Endpoint Target Binding (Fetch and write stream sequences in a single wrapper)
+- Clean API Namespace (Unified module boundaries with zero complex configuration maps)
+
+---
+
+## Quick Usage Reference
+
+### Download, Normalize, and Export an API Stream to Disk
+
+```python
+import jsonunwrap as ju
+
+target_url = "url"
+output_file = "data/normalized_users.csv"
+
+# Fetch, unwrap nested schemas, and generate a local CSV payload
+df = ju.json_to_csv(target_url, output_file)
+```
+
+---
+
+## Core API Documentation
+
+The complete package interaction map exposes three primary interfaces:
+
+### `jsonunwrap.unwrap_data(data)`
+Recursively flattens an in-memory dictionary or list of records. Returns a parsed `pandas.DataFrame`.
+
+### `jsonunwrap.fetch_json(url, **kwargs)`
+A connection delivery utility utilizing the `requests` transport subsystem. Passes `**kwargs` onwards to target handlers.
+
+### `jsonunwrap.json_to_csv(url, output_path)`
+High-level workflow coordinator connecting remote schema acquisition loops directly to a structural local CSV export.
+
+---
+
+## Contributions & Testing
+
+To test modifications locally or prepare adjustments, execute using `pytest`:
+
+```bash
+\$ git clone https://github.com/njuedominic/json-unwrap
+\$ cd jsonunwrap
+\(python -m pip install -e .[test]\) pytest
+```

jsonunwrap-0.2.2/jsonunwrap/core.py

@@ -0,0 +1,99 @@
+"""
+This module contains the core functionality for the json_unwrap package.
+The main function is `json_to_csv`, which converts a JSON file to a CSV file.
+"""
+import os
+from typing import Any, Dict, List, Union
+import pandas as pd
+import requests
+
+def unwrap_data(data: Union[Dict[str, Any], List[Any]]) -> pd.DataFrame:
+    """
+    Normalizes and deeply flattens semi-structured JSON data into a pandas DataFrame.
+    """
+    # 1. Ensure we start with a clean record list
+    if isinstance(data, dict):
+        # Handle cases where the data is inside a wrapper key (like {"products": [...]})
+        list_keys = [k for k, v in data.items() if isinstance(v, list)]
+        if list_keys and len(data) <= 4:
+            main_data = data[list_keys[0]]
+        else:
+            main_data = [data]
+    else:
+        main_data = data
+
+    # 2. Base normalization
+    df = pd.json_normalize(main_data)
+
+    # 3. Clean Linear Pass: Avoid infinite loops by tracking column states directly
+    columns_to_process = list(df.columns)
+    
+    while columns_to_process:
+        col = columns_to_process.pop(0)
+        
+        # Guard check if the column was dropped in a previous iteration
+        if col not in df.columns:
+            continue
+            
+        non_null_vals = df[col].dropna()
+        if non_null_vals.empty:
+            continue
+
+        # Check for nested dictionaries
+        if any(isinstance(val, dict) for val in non_null_vals):
+            nested_df = pd.json_normalize(non_null_vals).set_index(non_null_vals.index)
+            # Add new sub-columns back into the processing queue
+            new_cols = [f"{c}_{col}" for c in nested_df.columns]
+            df = df.drop(columns=[col]).join(nested_df, rsuffix=f"_{col}")
+            columns_to_process.extend(new_cols)
+
+        # Check for nested lists (But do not loop back if it's just raw strings/ints)
+        elif any(isinstance(val, list) for val in non_null_vals):
+            # Check if the list contains dictionaries before exploding heavily
+            first_list = next((v for v in non_null_vals if isinstance(v, list) and v), None)
+            
+            df = df.explode(col)
+            
+            # If the inner elements were dictionaries, we need to flatten them on the next pass
+            if first_list and isinstance(first_list[0], dict):
+                columns_to_process.append(col)
+
+    return df
+
+ 
+def fetch_json(url: str, **kwargs: Any) -> Union[Dict[str, Any], List[Any]]:
+    """
+    Fetches raw JSON data from a URL.
+    
+    Args:
+        url: The endpoint web target.
+        **kwargs: Additional arguments passed directly to requests.get (e.g., headers, auth).
+    """
+    response = requests.get(url, **kwargs)
+    response.raise_for_status()
+    return response.json()
+
+
+def json_to_csv(url: str, output_path: str) -> pd.DataFrame:
+    """
+    Fetches JSON from a URL, deeply flattens it, and saves it directly to a CSV file.
+    
+    Args:
+        url: The endpoint URL containing the target JSON data.
+        output_path: Target filesystem path where the CSV will be written.
+        
+    Returns:
+        The generated pandas DataFrame.
+    """
+    # Ensure the parent output directory exists safely
+    directory = os.path.dirname(output_path)
+    if directory:
+        os.makedirs(directory, exist_ok=True)
+        
+    raw_data = fetch_json(url)
+    df = unwrap_data(raw_data)
+    
+    df.to_csv(output_path, index=False)
+    return df
+
+

jsonunwrap-0.2.2/jsonunwrap.egg-info/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: jsonunwrap
+Version: 0.2.2
+Summary: A small python package that unpacks data from a JSON url and converts it into a csv file.
+Author-email: njuedominic <njuemugodominic@gmail.com>
+Project-URL: Homepage, https://github.com/njuedominic/json-unwrap
+Project-URL: Bug Tracker, https://github.com/njuedominic/json-unwrap/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pandas>=2.0.0
+
+# jsonunwrap
+
+**jsonunwrap** is a simple JSON flattening and normalization library.
+
+```python
+>>> import jsonunwrap as ju
+>>> url = "https://dummyjson.com/carts"
+>>> fetchdata = ju.fetch_json(url)
+>>> df = ju.unwrap_data(fetchdata)
+>>> df.columns
+Index(['id', 'user.name', 'hobbies'], dtype='object')
+>>> len(df)
+2
+```
+
+jsonunwrap allows you to deeply normalize complex, semi-structured nested JSON data into clean pandas DataFrames extremely easily.
+
+---
+
+## Installing jsonunwrap
+
+jsonunwrap is available on PyPI:
+
+```bash
+$ python -m pip install jsonunwrap
+```
+
+## Supported Features & Best–Practices
+
+jsonunwrap is ready for the data parsing demands of modern web APIs, automation scripts, and data engineering pipelines.
+
+- Recursive Deep-Flattening (Dot-notation formatting for sub-dictionaries)
+- Automated List Explosion (Spanning embedded primitive lists safely into unique rows)
+- Endpoint Target Binding (Fetch and write stream sequences in a single wrapper)
+- Clean API Namespace (Unified module boundaries with zero complex configuration maps)
+
+---
+
+## Quick Usage Reference
+
+### Download, Normalize, and Export an API Stream to Disk
+
+```python
+import jsonunwrap as ju
+
+target_url = "url"
+output_file = "data/normalized_users.csv"
+
+# Fetch, unwrap nested schemas, and generate a local CSV payload
+df = ju.json_to_csv(target_url, output_file)
+```
+
+---
+
+## Core API Documentation
+
+The complete package interaction map exposes three primary interfaces:
+
+### `jsonunwrap.unwrap_data(data)`
+Recursively flattens an in-memory dictionary or list of records. Returns a parsed `pandas.DataFrame`.
+
+### `jsonunwrap.fetch_json(url, **kwargs)`
+A connection delivery utility utilizing the `requests` transport subsystem. Passes `**kwargs` onwards to target handlers.
+
+### `jsonunwrap.json_to_csv(url, output_path)`
+High-level workflow coordinator connecting remote schema acquisition loops directly to a structural local CSV export.
+
+---
+
+## Contributions & Testing
+
+To test modifications locally or prepare adjustments, execute using `pytest`:
+
+```bash
+\$ git clone https://github.com/njuedominic/json-unwrap
+\$ cd jsonunwrap
+\(python -m pip install -e .[test]\) pytest
+```

{jsonunwrap-0.2.0 → jsonunwrap-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "jsonunwrap"
-version = "0.2.0"
+version = "0.2.2"
 authors = [
     { name = "njuedominic", email="njuemugodominic@gmail.com"}
 ]

jsonunwrap-0.2.0/PKG-INFO

@@ -1,28 +0,0 @@
-Metadata-Version: 2.4
-Name: jsonunwrap
-Version: 0.2.0
-Summary: A small python package that unpacks data from a JSON url and converts it into a csv file.
-Author-email: njuedominic <njuemugodominic@gmail.com>
-Project-URL: Homepage, https://github.com/njuedominic/json-unwrap
-Project-URL: Bug Tracker, https://github.com/njuedominic/json-unwrap/issues
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >3.8
-Description-Content-Type: text/markdown
-Requires-Dist: requests>=2.28.0
-Requires-Dist: pandas>=2.0.0
-
-### JSON Unwrap
-A small python package that unpacks data from a JSON url and converts it into a csv file.
-
-### Current features
-* Convert one JSON url to a csv
-* Automatically creates a data folder if it does not exist
-
-### Roadmap
-* Custom file names for output csv
-* Convert into a dataframe ready for use in a notebook environment
-* Error handling for a failed url
-* Tests
-* Documentation examples

jsonunwrap-0.2.0/README.md

@@ -1,13 +0,0 @@
-### JSON Unwrap
-A small python package that unpacks data from a JSON url and converts it into a csv file.
-
-### Current features
-* Convert one JSON url to a csv
-* Automatically creates a data folder if it does not exist
-
-### Roadmap
-* Custom file names for output csv
-* Convert into a dataframe ready for use in a notebook environment
-* Error handling for a failed url
-* Tests
-* Documentation examples

jsonunwrap-0.2.0/jsonunwrap/core.py

@@ -1,79 +0,0 @@
-"""
-This module contains the core functionality for the json_unwrap package.
-The main function is `json_to_csv`, which converts a JSON file to a CSV file.
-"""
-import os
-from typing import Any, Dict, List, Union
-import pandas as pd
-import requests
-
-def unwrap_data(data: Union[Dict[str, Any], List[Any]]) -> pd.DataFrame:
-    """
-    Normalizes and deeply flattens semi-structured JSON data into a pandas DataFrame.
-    """
-    # Simply convert a single dictionary into a list containing that dictionary
-    if isinstance(data, dict):
-        main_data = [data]
-    else:
-        main_data = data
-
-    # Perform the initial normalization
-    df = pd.json_normalize(main_data)
-
-    # Automatically iterate through the columns and deeply flatten any nested structures
-    changed = True
-    while changed:
-        changed = False
-        for col in list(df.columns):
-            # Explode lists
-            if any(isinstance(val, list) for val in df[col].dropna()):
-                df = df.explode(col)
-                changed = True
-                break  # Refresh columns list after structural changes
-
-            # Normalize and merge nested dictionaries
-            if any(isinstance(val, dict) for val in df[col].dropna()):
-                nested_df = pd.json_normalize(df[col]).set_index(df.index)
-                df = df.drop(columns=[col]).join(nested_df, rsuffix=f"_{col}")
-                changed = True
-                break
-                
-    return df
-
- 
-def fetch_json(url: str, **kwargs: Any) -> Union[Dict[str, Any], List[Any]]:
-    """
-    Fetches raw JSON data from a URL.
-    
-    Args:
-        url: The endpoint web target.
-        **kwargs: Additional arguments passed directly to requests.get (e.g., headers, auth).
-    """
-    response = requests.get(url, **kwargs)
-    response.raise_for_status()
-    return response.json()
-
-
-def json_to_csv(url: str, output_path: str) -> pd.DataFrame:
-    """
-    Fetches JSON from a URL, deeply flattens it, and saves it directly to a CSV file.
-    
-    Args:
-        url: The endpoint URL containing the target JSON data.
-        output_path: Target filesystem path where the CSV will be written.
-        
-    Returns:
-        The generated pandas DataFrame.
-    """
-    # Ensure the parent output directory exists safely
-    directory = os.path.dirname(output_path)
-    if directory:
-        os.makedirs(directory, exist_ok=True)
-        
-    raw_data = fetch_json(url)
-    df = unwrap_data(raw_data)
-    
-    df.to_csv(output_path, index=False)
-    return df
-
-

jsonunwrap-0.2.0/jsonunwrap.egg-info/PKG-INFO

@@ -1,28 +0,0 @@
-Metadata-Version: 2.4
-Name: jsonunwrap
-Version: 0.2.0
-Summary: A small python package that unpacks data from a JSON url and converts it into a csv file.
-Author-email: njuedominic <njuemugodominic@gmail.com>
-Project-URL: Homepage, https://github.com/njuedominic/json-unwrap
-Project-URL: Bug Tracker, https://github.com/njuedominic/json-unwrap/issues
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >3.8
-Description-Content-Type: text/markdown
-Requires-Dist: requests>=2.28.0
-Requires-Dist: pandas>=2.0.0
-
-### JSON Unwrap
-A small python package that unpacks data from a JSON url and converts it into a csv file.
-
-### Current features
-* Convert one JSON url to a csv
-* Automatically creates a data folder if it does not exist
-
-### Roadmap
-* Custom file names for output csv
-* Convert into a dataframe ready for use in a notebook environment
-* Error handling for a failed url
-* Tests
-* Documentation examples