json-structure-summary 0.1.0__tar.gz

json_structure_summary-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Kingdom
+
+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_structure_summary-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: json-structure-summary
+Version: 0.1.0
+Summary: Infer and summarize the structure of any JSON file – even malformed ones – as a schema or human-readable tree.
+Author: Andrew Kingdom
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/akingdom/json-structure-summary
+Project-URL: Repository, https://github.com/akingdom/json-structure-summary
+Project-URL: Issues, https://github.com/akingdom/json-structure-summary/issues
+Keywords: json,schema,inference,validation,structural-analysis,cli,data-exploration
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0; extra == "test"
+Dynamic: license-file
+
+# JSON Structure Summary
+
+**Infer and summarise the structure of any JSON file – even malformed ones – as a JSON Schema or a human‑readable tree.**
+
+[![PyPI version](https://badge.fury.io/py/json-structure-summary.svg)](https://pypi.org/project/json-structure-summary/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Why do developers need this?
+
+Working with unknown JSON data is a common pain point:
+
+- You receive a large JSON file and have **no idea what’s inside**.
+- The file is **malformed** (trailing commas, C‑style comments) and breaks normal parsers.
+- You need to **generate a JSON Schema** for validation or documentation.
+- You want to **quickly understand the structure** without reading thousands of lines.
+- You need **statistics** (field presence, array lengths) to assess data quality.
+
+**json-structure-summary** solves these problems in one command. It:
+
+- **Repairs common JSON errors** (comments, trailing commas, BOM) automatically.
+- **Infers a JSON Schema** (draft‑07) that accurately describes the data, including union types, optional fields, and nested structures.
+- **Provides a human‑readable summary** with field presence and array length statistics.
+- **Works as a library** so you can integrate it into your own Python tools.
+
+Whether you’re exploring a new API response, debugging a data pipeline, or writing documentation, this tool gives you instant insight into your JSON data.
+
+---
+
+## Features
+
+- **Robust parsing** – strips `//` and `/* */` comments, removes trailing commas, handles byte‑order marks.
+- **Schema inference** – outputs a standard JSON Schema (draft‑07) that you can use with validators like `jsonschema`.
+- **Mixed‑type support** – arrays with different element types are represented using `anyOf`.
+- **Optionality detection** – fields are marked `required` only if they appear in *every* object across the dataset.
+- **Human‑readable summary** – prints a tree structure with type annotations and (optionally) statistics.
+- **Statistics** – shows field presence counts and array length ranges (min, max, average).
+- **Performance** – limit array sampling with `--max-samples` to handle huge files quickly.
+- **Library friendly** – import `summarize_json_structure()` and use it programmatically.
+
+---
+
+## Installation
+
+```bash
+pip install json-structure-summary
+```
+
+Or install directly from source:
+
+```bash
+git clone https://github.com/akingdom/json-structure-summary.git
+cd json-structure-summary
+pip install -e .
+```
+
+---
+
+## Usage
+
+### Command‑line interface
+
+```bash
+# Basic usage – outputs JSON Schema
+json-structure-summary data.json
+
+# Human‑readable summary with statistics
+json-structure-summary data.json --summary
+
+# Pretty‑print the schema
+json-structure-summary data.json --schema --pretty
+
+# Limit array sampling to 100 elements for performance
+json-structure-summary data.json --max-samples 100
+
+# Read from stdin
+cat data.json | json-structure-summary
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--schema` | Output a JSON Schema (default) |
+| `--summary` | Output a human‑readable structural summary |
+| `--pretty` | Pretty‑print the output (indent 2) |
+| `--max-samples N` | Inspect at most N elements per array (default: all) |
+| `--help` | Show help |
+
+---
+
+## Examples
+
+### Input JSON (with trailing commas and comments)
+
+```json
+{
+  "users": [  // list of users
+    {"id": 1, "name": "Alice", "active": true,},
+    {"id": 2, "name": "Bob", "active": false, "tags": ["admin"]}
+  ]
+}
+```
+
+### Output (schema, pretty‑printed)
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "users": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "integer" },
+          "name": { "type": "string" },
+          "active": { "type": "boolean" },
+          "tags": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "required": ["id", "name", "active"]   // 'tags' is optional
+      }
+    }
+  },
+  "required": ["users"]
+}
+```
+
+### Summary output
+
+```
+Object:
+  users:
+    Array of:
+      Object:
+        id:
+          integer
+        name:
+          string
+        active:
+          boolean
+        tags:
+          Array of:
+            string
+
+Statistics:
+  $.users: lengths 2-2 (avg 2.0, 1 entries)
+  $.users[0].id: present in 1 objects
+  $.users[0].name: present in 1 objects
+  ...
+```
+
+---
+
+## Using as a library
+
+```python
+from json_structure_summary import summarize_json_structure
+
+# From a file, get schema as string
+schema_str = summarize_json_structure('data.json', pretty=True)
+
+# From a file, get schema as dict
+schema_dict = summarize_json_structure('data.json', return_type='dict')
+
+# From a JSON string, get summary
+summary = summarize_json_structure(
+    '{"x": 1, "y": "hello"}',
+    from_file=False,
+    output_format='summary'
+)
+print(summary)
+```
+
+**Function signature:**
+
+```python
+summarize_json_structure(
+    source: str,
+    from_file: bool = True,
+    output_format: Literal['schema', 'summary'] = 'schema',
+    pretty: bool = False,
+    max_samples: Optional[int] = None,
+    return_type: Literal['str', 'dict'] = 'str'
+) -> Union[str, Dict]
+```
+
+---
+
+## License
+
+MIT License – see [LICENSE](LICENSE) for details.
+
+---
+
+## Contributing
+
+Bug reports, feature requests, and pull requests are welcome on [GitHub](https://github.com/akingdom/json-structure-summary).

json_structure_summary-0.1.0/README.md

@@ -0,0 +1,202 @@
+# JSON Structure Summary
+
+**Infer and summarise the structure of any JSON file – even malformed ones – as a JSON Schema or a human‑readable tree.**
+
+[![PyPI version](https://badge.fury.io/py/json-structure-summary.svg)](https://pypi.org/project/json-structure-summary/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Why do developers need this?
+
+Working with unknown JSON data is a common pain point:
+
+- You receive a large JSON file and have **no idea what’s inside**.
+- The file is **malformed** (trailing commas, C‑style comments) and breaks normal parsers.
+- You need to **generate a JSON Schema** for validation or documentation.
+- You want to **quickly understand the structure** without reading thousands of lines.
+- You need **statistics** (field presence, array lengths) to assess data quality.
+
+**json-structure-summary** solves these problems in one command. It:
+
+- **Repairs common JSON errors** (comments, trailing commas, BOM) automatically.
+- **Infers a JSON Schema** (draft‑07) that accurately describes the data, including union types, optional fields, and nested structures.
+- **Provides a human‑readable summary** with field presence and array length statistics.
+- **Works as a library** so you can integrate it into your own Python tools.
+
+Whether you’re exploring a new API response, debugging a data pipeline, or writing documentation, this tool gives you instant insight into your JSON data.
+
+---
+
+## Features
+
+- **Robust parsing** – strips `//` and `/* */` comments, removes trailing commas, handles byte‑order marks.
+- **Schema inference** – outputs a standard JSON Schema (draft‑07) that you can use with validators like `jsonschema`.
+- **Mixed‑type support** – arrays with different element types are represented using `anyOf`.
+- **Optionality detection** – fields are marked `required` only if they appear in *every* object across the dataset.
+- **Human‑readable summary** – prints a tree structure with type annotations and (optionally) statistics.
+- **Statistics** – shows field presence counts and array length ranges (min, max, average).
+- **Performance** – limit array sampling with `--max-samples` to handle huge files quickly.
+- **Library friendly** – import `summarize_json_structure()` and use it programmatically.
+
+---
+
+## Installation
+
+```bash
+pip install json-structure-summary
+```
+
+Or install directly from source:
+
+```bash
+git clone https://github.com/akingdom/json-structure-summary.git
+cd json-structure-summary
+pip install -e .
+```
+
+---
+
+## Usage
+
+### Command‑line interface
+
+```bash
+# Basic usage – outputs JSON Schema
+json-structure-summary data.json
+
+# Human‑readable summary with statistics
+json-structure-summary data.json --summary
+
+# Pretty‑print the schema
+json-structure-summary data.json --schema --pretty
+
+# Limit array sampling to 100 elements for performance
+json-structure-summary data.json --max-samples 100
+
+# Read from stdin
+cat data.json | json-structure-summary
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--schema` | Output a JSON Schema (default) |
+| `--summary` | Output a human‑readable structural summary |
+| `--pretty` | Pretty‑print the output (indent 2) |
+| `--max-samples N` | Inspect at most N elements per array (default: all) |
+| `--help` | Show help |
+
+---
+
+## Examples
+
+### Input JSON (with trailing commas and comments)
+
+```json
+{
+  "users": [  // list of users
+    {"id": 1, "name": "Alice", "active": true,},
+    {"id": 2, "name": "Bob", "active": false, "tags": ["admin"]}
+  ]
+}
+```
+
+### Output (schema, pretty‑printed)
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "users": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "integer" },
+          "name": { "type": "string" },
+          "active": { "type": "boolean" },
+          "tags": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "required": ["id", "name", "active"]   // 'tags' is optional
+      }
+    }
+  },
+  "required": ["users"]
+}
+```
+
+### Summary output
+
+```
+Object:
+  users:
+    Array of:
+      Object:
+        id:
+          integer
+        name:
+          string
+        active:
+          boolean
+        tags:
+          Array of:
+            string
+
+Statistics:
+  $.users: lengths 2-2 (avg 2.0, 1 entries)
+  $.users[0].id: present in 1 objects
+  $.users[0].name: present in 1 objects
+  ...
+```
+
+---
+
+## Using as a library
+
+```python
+from json_structure_summary import summarize_json_structure
+
+# From a file, get schema as string
+schema_str = summarize_json_structure('data.json', pretty=True)
+
+# From a file, get schema as dict
+schema_dict = summarize_json_structure('data.json', return_type='dict')
+
+# From a JSON string, get summary
+summary = summarize_json_structure(
+    '{"x": 1, "y": "hello"}',
+    from_file=False,
+    output_format='summary'
+)
+print(summary)
+```
+
+**Function signature:**
+
+```python
+summarize_json_structure(
+    source: str,
+    from_file: bool = True,
+    output_format: Literal['schema', 'summary'] = 'schema',
+    pretty: bool = False,
+    max_samples: Optional[int] = None,
+    return_type: Literal['str', 'dict'] = 'str'
+) -> Union[str, Dict]
+```
+
+---
+
+## License
+
+MIT License – see [LICENSE](LICENSE) for details.
+
+---
+
+## Contributing
+
+Bug reports, feature requests, and pull requests are welcome on [GitHub](https://github.com/akingdom/json-structure-summary).

json_structure_summary-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "json-structure-summary"
+dynamic = ["version"]
+description = "Infer and summarize the structure of any JSON file – even malformed ones – as a schema or human-readable tree."
+readme = "README.md"
+requires-python = ">=3.7"
+license = "MIT"
+authors = [
+    { name = "Andrew Kingdom" }
+]
+keywords = [
+    "json",
+    "schema",
+    "inference",
+    "validation",
+    "structural-analysis",
+    "cli",
+    "data-exploration"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.7",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = []  # only uses the standard library
+
+[project.optional-dependencies]
+test = ["pytest>=7.0", "pytest-cov>=4.0"]
+
+[project.urls]
+Homepage = "https://github.com/akingdom/json-structure-summary"
+Repository = "https://github.com/akingdom/json-structure-summary"
+Issues = "https://github.com/akingdom/json-structure-summary/issues"
+
+[project.scripts]
+json-structure-summary = "json_structure_summary:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "json_structure_summary.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+# This will automatically find any package under src/ that is a valid Python package name.
+# Our package is now "json_structure_summary" (with underscores) – it will be discovered.
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+addopts = "-ra -q --cov=json_structure_summary --cov-report=term-missing"
+testpaths = ["tests"]   # change to "test" if you keep that folder
+python_files = "test_*.py"

json_structure_summary-0.1.0/setup.cfg

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

json_structure_summary-0.1.0/src/json_structure_summary/__init__.py

@@ -0,0 +1,10 @@
+"""json_structure_summary: Infer and summarize the structure of any JSON file, even malformed ones."""
+
+from .core import summarize_json_structure, main
+
+__version__ = "0.1.0"
+__all__ = [
+    "__version__",
+    "summarize_json_structure",
+    "main",
+]