python 3.11+ and centralized logging

Author: MS-32154

json_explorer/__init__.py

@@ -1 +1,31 @@
-__version__ = "0.3.0"
+"""JSON Explorer - Comprehensive JSON analysis and code generation tool."""
+
+from .logging_config import configure_logging, get_logger
+from .analyzer import analyze_json
+from .search import JsonSearcher, SearchMode, SearchResult
+from .stats import DataStatsAnalyzer, generate_stats
+from .visualizer import JSONVisualizer, visualize_json
+from .utils import load_json, JSONLoaderError
+
+__version__ = "0.4.0"
+
+__all__ = [
+    # Logging
+    "configure_logging",
+    "get_logger",
+    # Core
+    "analyze_json",
+    "load_json",
+    # Search
+    "JsonSearcher",
+    "SearchMode",
+    "SearchResult",
+    # Statistics
+    "DataStatsAnalyzer",
+    "generate_stats",
+    # Visualization
+    "JSONVisualizer",
+    "visualize_json",
+    # Exceptions
+    "JSONLoaderError",
+]

json_explorer/analyzer.py

@@ -1,26 +1,72 @@
+"""JSON structure analyzer with type detection and schema inference.
+
+This module analyzes JSON data structures to detect types, optional fields,
+conflicts, and generates comprehensive structural summaries.
+"""
+
 from collections import Counter
+from typing import Any
+
 import dateparser
 from rich.progress import Progress, SpinnerColumn, TextColumn
 
+from .logging_config import get_logger
+
+logger = get_logger(__name__)
+
 
-def detect_timestamp(value):
+def detect_timestamp(value: Any) -> bool:
+    """Detect if a string value is a timestamp.
+
+    Args:
+        value: Value to check.
+
+    Returns:
+        True if the value is a parseable timestamp, False otherwise.
+    """
     if not isinstance(value, str) or len(value) < 4:
         return False
-    parsed = dateparser.parse(value)
-    return parsed is not None
 
+    try:
+        parsed = dateparser.parse(value)
+        return parsed is not None
+    except Exception:
+        return False
+
+
+def analyze_json(data: Any) -> dict[str, Any]:
+    """Analyze JSON structure and return detailed metadata.
+
+    This function performs deep structural analysis of JSON data, identifying:
+    - Data types and their distribution
+    - Optional and required fields
+    - Type conflicts across similar structures
+    - Nested object and array patterns
+
+    Args:
+        data: JSON data to analyze (dict, list, or primitive type).
+
+    Returns:
+        Dictionary containing analysis summary with structure, types, and conflicts.
+
+    Example:
+        >>> data = {"users": [{"id": 1, "name": "Alice"}]}
+        >>> analysis = analyze_json(data)
+        >>> print(analysis['type'])
+        'object'
+    """
+    logger.info("Starting JSON analysis")
 
-def analyze_json(data):
     with Progress(
         SpinnerColumn(),
         TextColumn("[progress.description]{task.description}"),
         console=None,
         transient=True,
     ) as progress:
-
         task = progress.add_task("[cyan]Analyzing JSON...", total=None)
 
-        def analyze_node(node):
+        def analyze_node(node: Any) -> dict[str, Any]:
+            """Recursively analyze a node in the JSON structure."""
             if isinstance(node, dict):
                 children = {}
                 for key, val in node.items():
@@ -60,17 +106,12 @@ def analyze_node(node):
 
                 # List of lists
                 if all(e["type"] == "list" for e in element_summaries):
-                    # Merge list structures recursively
                     merged_list = merge_list_summaries(element_summaries)
-                    return {
-                        "type": "list",
-                        "child": merged_list,
-                    }
+                    return {"type": "list", "child": merged_list}
 
                 return {"type": "list", "child_type": "mixed"}
 
             elif node is None:
-                # Explicitly handle None - mark as unknown but with a flag
                 return {"type": "unknown", "is_none": True}
 
             else:
@@ -82,8 +123,11 @@ def analyze_node(node):
                 else:
                     return {"type": type(node).__name__}
 
-        def merge_object_summaries(summaries):
-            key_structures = {}
+        def merge_object_summaries(
+            summaries: list[dict[str, Any]],
+        ) -> tuple[dict[str, Any], dict[str, list[str]]]:
+            """Merge multiple object summaries, detecting optional fields and conflicts."""
+            key_structures: dict[str, list] = {}
             key_counts = Counter()
             key_none_counts = Counter()
             total = len(summaries)
@@ -95,45 +139,38 @@ def merge_object_summaries(summaries):
                     key_counts[key] += 1
                     seen_keys.add(key)
 
-                    # Track if this value is None/unknown
                     if val.get("type") == "unknown":
                         key_none_counts[key] += 1
 
                     if key not in key_structures:
                         key_structures[key] = []
                     key_structures[key].append(val)
 
-            merged = {}
-            conflicts = {}
+            merged: dict[str, Any] = {}
+            conflicts: dict[str, list[str]] = {}
 
             for key, structures in key_structures.items():
                 count = key_counts[key]
                 none_count = key_none_counts[key]
 
-                # Field is optional if:
-                # 1. Missing from some objects (count < total)
-                # 2. Has None in some objects (none_count > 0)
+                # Field is optional if missing or has None values
                 optional = (count < total) or (none_count > 0)
 
-                # Filter out None/unknown types to find concrete types
+                # Filter out None/unknown types
                 concrete_structures = [
                     s for s in structures if s.get("type") != "unknown"
                 ]
 
-                # If we have concrete types, use those; otherwise use all structures
                 working_structures = (
                     concrete_structures if concrete_structures else structures
                 )
 
-                # Get unique types from working structures
                 types = {s["type"] for s in working_structures}
 
                 if len(types) == 1:
-                    # Single type (possibly with None values)
                     structure_type = list(types)[0]
 
                     if structure_type == "object":
-                        # Recursively merge object structures
                         merged_children, child_conflicts = merge_object_summaries(
                             working_structures
                         )
@@ -146,7 +183,6 @@ def merge_object_summaries(summaries):
                             merged[key]["conflicts"] = child_conflicts
 
                     elif structure_type == "list":
-                        # Merge list structures
                         merged_list = merge_list_summaries(working_structures)
                         merged[key] = {
                             "type": "list",
@@ -155,21 +191,19 @@ def merge_object_summaries(summaries):
                         }
 
                     else:
-                        # Primitive type (possibly with None)
                         merged[key] = {"type": structure_type, "optional": optional}
 
                 elif len(types) > 1:
-                    # Multiple different types = real conflict
                     merged[key] = {"type": "conflict", "optional": optional}
                     conflicts[key] = list(types)
 
                 else:
-                    # Should not happen, but handle gracefully
                     merged[key] = {"type": "unknown", "optional": optional}
 
             return merged, conflicts
 
-        def merge_list_summaries(summaries):
+        def merge_list_summaries(summaries: list[dict[str, Any]]) -> dict[str, Any]:
+            """Merge multiple list summaries."""
             child_types = set()
             child_structures = []
 
@@ -180,14 +214,12 @@ def merge_list_summaries(summaries):
                     child_structures.append(summary["child"])
 
             if child_structures:
-                # All lists contain complex structures
                 structure_types = {s["type"] for s in child_structures}
 
                 if len(structure_types) == 1:
                     structure_type = list(structure_types)[0]
 
                     if structure_type == "object":
-                        # Merge object structures within lists
                         merged_children, child_conflicts = merge_object_summaries(
                             child_structures
                         )
@@ -200,14 +232,12 @@ def merge_list_summaries(summaries):
                             },
                         }
                     elif structure_type == "list":
-                        # Nested lists
                         merged_nested = merge_list_summaries(child_structures)
                         return {"type": "list", "child": merged_nested}
 
                 return {"type": "list", "child_type": "mixed_complex"}
 
             elif child_types:
-                # Simple child types
                 if len(child_types) == 1:
                     return {"type": "list", "child_type": list(child_types)[0]}
                 else:
@@ -218,45 +248,6 @@ def merge_list_summaries(summaries):
 
             return {"type": "list", "child_type": "unknown"}
 
-        # Start the analysis
         result = analyze_node(data)
+        logger.info("JSON analysis completed successfully")
         return result
-
-
-if __name__ == "__main__":
-    from rich import print as rprint
-    from rich.pretty import pretty_repr
-
-    test_data = {
-        "users": [
-            {
-                "id": 1,
-                "name": "Alice",
-                "profile": {
-                    "age": 30,
-                    "settings": {"theme": "dark", "notifications": True},
-                },
-                "tags": ["admin", "user"],
-                "last_login": "2024-07-15T12:30:00Z",
-            },
-            {
-                "id": 2,
-                "name": "Bob",
-                "profile": {
-                    "age": 25,
-                    "settings": {
-                        "theme": "light",
-                        "notifications": False,
-                        "language": "en",
-                    },
-                },
-                "tags": ["user"],
-                "email": "[email protected]",
-                "last_login": "not a date",
-            },
-        ],
-        "metadata": {"total": 2, "created": "2024-01-01"},
-    }
-
-    summary = analyze_json(test_data)
-    rprint(pretty_repr(summary))