py-json-analyzer 0.4.0

A powerful CLI and Python library for analyzing, visualizing, exploring, and generating code from JSON data

JSON Explorer

JSON Explorer is a powerful CLI and Python library for analyzing, visualizing, exploring, and generating code from JSON data. Built with modern Python practices and featuring JMESPath-powered search capabilities.

---

Features

Analysis & Exploration

• Structural Analysis: Deep JSON structure analysis with type detection and conflict resolution
• JMESPath Search: Industry-standard query language for powerful JSON searching and filtering
• Tree Visualization: Multiple view modes (compact, analytical, raw) with rich terminal output
• Statistical Analysis: Comprehensive data quality metrics and structural insights
• Multi-Format Visualization: Terminal (curses/ASCII), interactive HTML (Plotly), or combined output
• Interactive Mode: Full-featured terminal UI for exploration and analysis

Code Generation

• Multi-Language Support: Generate strongly-typed code from JSON schemas
  • Go: Structs with JSON tags, pointer handling, configurable types
  • Python: Dataclasses, Pydantic v2 models, TypedDict with type hints
  • Coming Soon: TypeScript interfaces, Rust structs with Serde
• Smart Type Detection: Automatic conflict resolution and optional field handling
• Flexible Configuration: Template-based system with extensive customization
• Interactive Configuration: Guided setup with real-time preview and validation

Library Features

• Modular Architecture: Use individual components independently
• Extensible Design: Plugin-based generator system for custom languages
• Production Ready: Comprehensive error handling and logging
• Well Documented: Extensive API documentation and examples

---

Requirements

• Python: 3.11 or higher

Core Dependencies

dateparser>=1.2.0        # Timestamp detection
jmespath>=1.0.1          # JMESPath query language
jinja2>=3.0.0            # Template engine for code generation
plotly>=5.0.0            # Interactive, browser-based graphing
prompt-toolkit>=3.0.0    # Interactive input with autocomplete
requests>=2.32.0         # HTTP requests for URL loading
rich>=13.0.0             # Rich terminal formatting
windows-curses>=2.4.0    # Terminal UI support on Windows (auto-installed)

Optional Dependencies

pytest>=7.0.0
pytest-cov>=4.0.0
black>=23.0.0
isort>=5.12.0
mypy>=1.0.0
flake8>=6.0.0
types-requests>=2.31.0
types-dateparser>=1.1.0

---

Installation

From PyPI (Recommended)

pip install py-json-analyzer

Upgrade to the latest version:

pip install --upgrade py-json-analyzer

From Source

git clone https://github.com/MS-32154/py-json-analyzer
cd py-json-analyzer
pip install -e .

For development with all optional dependencies:

pip install -e ".[dev]"

---

Quick Start

Command Line

# Interactive mode (recommended for first-time users)
json_explorer data.json --interactive

# Quick analysis
json_explorer data.json --tree compact --stats

# JMESPath search
json_explorer data.json --search "users[*].email"

# Generate Go code
json_explorer data.json --generate go --output models.go

# Generate Pydantic models
json_explorer data.json --generate python --python-style pydantic --output models.py

# Create visualizations
json_explorer data.json --plot --plot-format html

Python Library

from json_explorer import analyze_json, JsonSearcher, quick_generate

# Analyze structure
data = {"users": [{"id": 1, "name": "Alice", "email": "[e-mail]"}]}
analysis = analyze_json(data)
print(analysis)

# JMESPath search
searcher = JsonSearcher()
result = searcher.search(data, "users[*].email")
searcher.print_result(result)

# Generate code
go_code = quick_generate(data, language="go", package_name="models")
python_code = quick_generate(data, language="python", style="pydantic")

---

CLI Usage

Basic Commands

json_explorer [FILE] [OPTIONS]

# Data Sources
json_explorer data.json              # Load from file
json_explorer --url https://api.example.com/data  # Load from URL

# Display Modes
--interactive, -i                    # Interactive mode (full UI)
--tree {compact,analysis,raw}        # Display tree structure
--stats                              # Show statistics
--detailed                           # Show detailed information
--plot                               # Generate visualizations

JMESPath Search

The search functionality now uses JMESPath, an industry-standard query language for JSON:

# Basic path expressions
json_explorer data.json --search "users"              # Get users array
json_explorer data.json --search "users[0]"           # First user
json_explorer data.json --search "users[*].name"      # All names

# Filtering
json_explorer data.json --search "users[?age > \`30\`]"           # Filter by age
json_explorer data.json --search "users[?active == \`true\`]"     # Filter by boolean

# Functions
json_explorer data.json --search "length(users)"                  # Count users
json_explorer data.json --search "sort_by(users, &age)"          # Sort by field
json_explorer data.json --search "max_by(users, &age).name"      # Get name of oldest

# Projections (field selection)
json_explorer data.json --search "users[*].{name: name, email: email}"

# Complex queries
json_explorer data.json --search "users[?age > \`30\` && active == \`true\`].name"

# Display options
--tree-results                       # Show results as tree
--show-examples                      # Display JMESPath examples

JMESPath Resources:

• Tutorial
• Specification
• Online Playground

Code Generation

# List supported languages
json_explorer --list-languages

# Get language details
json_explorer --language-info go
json_explorer --language-info python

# Generate Go code
json_explorer data.json --generate go \
  --output models.go \
  --package-name models \
  --root-name User

# Go-specific options
--no-pointers                        # Don't use pointers for optional fields
--no-json-tags                       # Don't generate JSON tags
--json-tag-case {original,snake,camel}

# Generate Python code
json_explorer data.json --generate python \
  --output models.py \
  --python-style {dataclass,pydantic,typeddict}

# Python-specific options
--frozen                             # Make dataclasses immutable
--no-slots                           # Don't use __slots__
--kw-only                            # Make fields keyword-only
--pydantic-forbid-extra              # Forbid extra fields in Pydantic

# Common options
--config config.json                 # Load configuration from file
--struct-case {pascal,camel,snake}   # Class/struct name convention
--field-case {pascal,camel,snake}    # Field name convention
--no-comments                        # Don't generate comments
--verbose                            # Show detailed generation info

Visualization

# Terminal visualization (ASCII/curses)
json_explorer data.json --plot --plot-format terminal

# Interactive HTML (Plotly)
json_explorer data.json --plot --plot-format html

# All formats
json_explorer data.json --plot --plot-format all

# Options
--detailed                           # Generate detailed charts
--save-path output.html              # Save to specific file
--no-browser                         # Don't auto-open browser

Logging

--log-level {DEBUG,INFO,WARNING,ERROR}
--log-file output.log
--verbose-logging, -vl

---

Python API

Core Analysis

from json_explorer import analyze_json, load_json

# Load data
source, data = load_json("data.json")
# or
source, data = load_json(url="https://api.example.com/data")

# Analyze structure
analysis = analyze_json(data)
print(f"Type: {analysis['type']}")
print(f"Children: {analysis.get('children', {})}")
print(f"Conflicts: {analysis.get('conflicts', {})}")

JMESPath Search

from json_explorer import JsonSearcher

searcher = JsonSearcher()

# Basic search
result = searcher.search(data, "users[*].email")
if result:
    searcher.print_result(result)

# Multiple queries
queries = [
    "users[*].name",
    "users[?age > `30`]",
    "length(users)"
]
results = searcher.search_multiple(data, queries)

# Validate query before executing
valid, error = searcher.validate_query("users[*].invalid...")
if valid:
    result = searcher.search(data, query)

# Get example queries
examples = searcher.get_query_examples()
searcher.print_examples()

Statistics & Analysis

from json_explorer import DataStatsAnalyzer, generate_stats

# Generate statistics
analyzer = DataStatsAnalyzer()
stats = analyzer.generate_stats(data)

# Print formatted summary
analyzer.print_summary(data, detailed=True)

# Or use convenience function
stats = generate_stats(data)
print(f"Total values: {stats['total_values']}")
print(f"Max depth: {stats['max_depth']}")
print(f"Complexity: {stats['computed_insights']['complexity_score']}")

Visualization

from json_explorer import JSONVisualizer, visualize_json

# Create visualizer
visualizer = JSONVisualizer()

# Terminal visualization
visualizer.visualize(data, output="terminal", detailed=True)

# HTML visualization
visualizer.visualize(
    data,
    output="html",
    save_path="report.html",
    detailed=True,
    open_browser=True
)

# Or use convenience function
visualize_json(data, output="html", detailed=True)

Tree Display

from json_explorer import print_json_analysis, print_compact_tree

# Full analysis with tree
print_json_analysis(data, source="API Response", show_raw=False)

# Compact tree (no annotations)
print_compact_tree(data, source="Config File")

# Custom tree builder
from json_explorer.tree_view import JsonTreeBuilder

builder = JsonTreeBuilder(show_conflicts=True, show_optional=True)
# ... use builder for custom visualization

Code Generation

from json_explorer.codegen import (
    quick_generate,
    generate_from_analysis,
    create_config,
    list_supported_languages,
    get_language_info
)

# Quick generation
go_code = quick_generate(
    data,
    language="go",
    package_name="models",
    root_name="User"
)

python_code = quick_generate(
    data,
    language="python",
    style="pydantic",
    package_name="models"
)

# Detailed workflow
analysis = analyze_json(data)
config = create_config(
    language="go",
    package_name="api",
    add_comments=True,
    language_config={
        "use_pointers_for_optional": True,
        "int_type": "int64"
    }
)

result = generate_from_analysis(analysis, "go", config, "User")
if result.success:
    print(result.code)
    with open("models.go", "w") as f:
        f.write(result.code)
else:
    print(f"Error: {result.error_message}")

# Discover capabilities
languages = list_supported_languages()
print(f"Supported: {languages}")

info = get_language_info("python")
print(f"Python styles: {info.get('styles', [])}")

Interactive Mode

from json_explorer import InteractiveHandler

handler = InteractiveHandler()
handler.set_data(data, source="my_data.json")
exit_code = handler.run()  # Launches interactive UI

---

Configuration

Configuration File Format

JSON Explorer uses JSON configuration files for code generation:

{
  "package_name": "models",
  "add_comments": true,
  "struct_case": "pascal",
  "field_case": "snake",
  "generate_json_tags": true,
  "json_tag_omitempty": true,
  "language_config": {
    "use_pointers_for_optional": true,
    "int_type": "int64",
    "float_type": "float64"
  }
}

Language-Specific Examples

Go Configuration

{
  "package_name": "api",
  "add_comments": true,
  "generate_json_tags": true,
  "json_tag_omitempty": true,
  "json_tag_case": "snake",
  "struct_case": "pascal",
  "field_case": "pascal",
  "language_config": {
    "use_pointers_for_optional": true,
    "int_type": "int64",
    "float_type": "float64"
  }
}

Python Dataclass Configuration

{
  "package_name": "models",
  "add_comments": true,
  "struct_case": "pascal",
  "field_case": "snake",
  "language_config": {
    "style": "dataclass",
    "dataclass_slots": true,
    "dataclass_frozen": false,
    "dataclass_kw_only": false,
    "use_optional": true
  }
}

Python Pydantic Configuration

{
  "package_name": "models",
  "add_comments": true,
  "struct_case": "pascal",
  "field_case": "snake",
  "language_config": {
    "style": "pydantic",
    "pydantic_use_field": true,
    "pydantic_use_alias": true,
    "pydantic_config_dict": true,
    "pydantic_extra_forbid": false,
    "use_optional": true
  }
}

Load configuration:

json_explorer data.json --generate go --config go_config.json

from json_explorer.codegen import load_config, generate_from_analysis

config = load_config("go_config.json")
result = generate_from_analysis(analysis, "go", config, "User")

---

Architecture

Project Structure

json_explorer/
├── __init__.py              # Public API exports
├── __main__.py              # Entry point for `python -m json_explorer`
├── main.py                  # CLI application coordinator
├── cli.py                   # CLI command handler
├── interactive.py           # Interactive mode handler
│
├── analyzer.py              # JSON structure analysis
├── search.py                # JMESPath-based search
├── stats.py                 # Statistical analysis
├── tree_view.py             # Tree visualization
├── visualizer.py            # Multi-format charts (Plotly/curses)
├── utils.py                 # File/URL loading utilities
├── logging_config.py        # Centralized logging
│
└── codegen/
    ├── __init__.py          # Code generation API
    ├── registry.py          # Generator registry system
    ├── cli_integration.py   # CLI integration
    ├── interactive.py       # Interactive codegen UI
    │
    ├── core/                # Core codegen infrastructure
    │   ├── naming.py        # Naming convention system
    │   ├── config.py        # Configuration management
    │   ├── templates.py     # Template engine
    │   ├── schema.py        # Internal schema representation
    │   └── generator.py     # Base generator interface
    │
    └── languages/           # Language-specific generators
        ├── go/
        │   ├── generator.py
        │   ├── config.py
        │   ├── naming.py
        │   ├── interactive.py
        │   └── templates/   # Jinja2 templates
        │
        └── python/
            ├── generator.py
            ├── config.py
            ├── naming.py
            ├── interactive.py
            └── templates/   # Jinja2 templates

Key Design Patterns

• Registry Pattern: Extensible generator system
• Template Method: Base generator defines workflow
• Strategy Pattern: Multiple naming conventions and styles
• Factory Pattern: Generator creation and configuration
• Builder Pattern: Schema construction from analysis

---

Testing

Run the test suite:

pytest

Run with coverage:

pytest --cov=json_explorer --cov-report=html

Test categories:

• Core modules: analyzer, search, stats, tree_view, visualizer
• Codegen core: naming, schema, config, templates
• Generators: Go and Python (all styles)
• Integration: End-to-end workflows
• Edge cases: None handling, conflicts, deep nesting

---

Supported Languages

Language	Status	Features
Go	✅ Full Support	Structs, JSON tags, pointers, customizable type mappings
Python	✅ Full Support	Dataclasses, Pydantic v2, TypedDict, modern type hints
TypeScript	🚧 Coming Soon	Interfaces, types, optional properties
Rust	🚧 Coming Soon	Structs, Serde annotations, Option types

---

Documentation

• API Documentation: https://ms-32154.github.io/py-json-analyzer/
• GitHub Repository: https://github.com/MS-32154/py-json-analyzer
• Issue Tracker: https://github.com/MS-32154/py-json-analyzer/issues

---

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Clone your fork: git clone https://github.com/YOUR_USERNAME/py-json-analyzer
3. Create a feature branch: git checkout -b feature/amazing-feature
4. Make your changes and add tests
5. Run tests: pytest
6. Commit: git commit -m 'Add amazing feature'
7. Push: git push origin feature/amazing-feature
8. Open a Pull Request

Development Setup

# Clone and setup
git clone https://github.com/MS-32154/py-json-analyzer
cd py-json-analyzer
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black json_explorer/
isort json_explorer/

# Type checking (if using mypy)
mypy json_explorer/

Adding a New Language Generator

1. Create json_explorer/codegen/languages/yourlang/
2. Implement generator.py extending CodeGenerator
3. Create templates in templates/
4. Register in json_explorer/codegen/languages/__init__.py
5. Add tests in tests/codegen/languages/test_yourlang.py

---

Support

Getting Help

• Documentation: Check the API docs
• Examples: See the examples section above
• Issues: GitHub Issues

Reporting Issues

When reporting issues, please include:

1. Python version: python --version
2. Package version: pip show py-json-analyzer
3. Operating system
4. Minimal reproducible example
5. Full error traceback
6. Expected vs actual behavior

Feature Requests

We welcome feature requests! Please open an issue with:

• Clear description of the feature
• Use cases and benefits
• Example of how it would work
• Any relevant mockups or examples

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Acknowledgments

• JMESPath: Powerful JSON query language
• Rich: Beautiful terminal formatting
• Plotly: Interactive visualizations
• Jinja2: Flexible template engine

---

Author

MS-32154

• GitHub: @MS-32154
• Email: [e-mail]

---

JSON Explorer – © 2025 MS-32154. All rights reserved.