headson 0.4.0__cp310-abi3-win_amd64.whl

headson/__init__.py

@@ -0,0 +1,4 @@
+# Re-export the public API from the compiled extension submodule
+from .headson import summarize  # type: ignore
+
+__all__ = ["summarize"]

headson-0.4.0.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: headson
+Version: 0.4.0
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Operating System :: OS Independent
+Requires-Dist: pytest>=8 ; extra == 'test'
+Provides-Extra: test
+License-File: LICENSE
+Summary: Budget‑constrained JSON preview renderer (Python bindings)
+Keywords: json,preview,summarize,cli,bindings
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# headson
+
+Head/tail for JSON — but structure‑aware. Get a compact preview that shows both the shape and representative values of your data, all within a strict character budget.
+
+Available as:
+- CLI (see [Usage](#usage))
+- Python library (see [Python Bindings](#python-bindings))
+
+## Install
+
+Using Cargo:
+
+    cargo install headson
+
+From source:
+
+    cargo build --release
+    target/release/headson --help
+
+
+## Features
+
+- *Budgeted output*: specify exactly how much JSON you want to see
+- *Multiple output formats* : `json` (machine‑readable), `pseudo` (human‑friendly), `js` (valid JavaScript, most detailed metadata).
+- *Multiple inputs*: preview many files at once with a shared or per‑file budget.
+- *Fast*: can process gigabyte-scale files in seconds (mostly disk-constrained)
+- *Available as a CLI app and as a Python library*
+
+## Fits into command line workflows
+
+If you’re comfortable with tools like `head` and `tail`, use `headson` when you want a quick, structured peek into a JSON file without dumping the entire thing.
+
+- `head`/`tail` operate on bytes/lines - their output is not optimized for tree structures
+- `jq` you need to craft filters to preview large JSON files
+- `headson` is like head/tail for trees: zero config but it keeps structure and represents content as much as possible 
+
+## Usage
+
+    headson [FLAGS] [INPUT...]
+
+- INPUT (optional, repeatable): file path(s). If omitted, reads JSON from stdin. Multiple input files are supported.
+- Prints the preview to stdout. On parse errors, exits non‑zero and prints an error to stderr.
+
+Common flags:
+
+- `-n, --budget <BYTES>`: per‑file output budget. When multiple input files are provided, the total budget equals `<BYTES> * number_of_inputs`.
+- `-N, --global-budget <BYTES>`: total output budget across all inputs. Useful when you want a fixed-size preview across many files (may omit entire files). Mutually exclusive with `--budget`.
+- `-f, --template <json|pseudo|js>`: output style (default: `pseudo`)
+- `-m, --compact`: no indentation, no spaces, no newlines
+- `--no-newline`: single line output
+- `--no-space`: no space after `:` in objects
+- `--indent <STR>`: indentation unit (default: two spaces)
+- `--string-cap <N>`: max graphemes to consider per string (default: 500)
+- `--tail`: prefer the end of arrays when truncating. Strings are unaffected. In `pseudo`/`js` templates the omission marker appears at the start; `json` remains strict JSON with no annotations.
+
+Notes:
+
+- With multiple input files:
+  - JSON template outputs a single JSON object keyed by the input file paths.
+  - Pseudo and JS templates render file sections with human-readable headers when newlines are enabled.
+    - If you use `--compact` or `--no-newline` (both disable newlines), fileset output falls back to standard inline rendering (no per-file headers) to remain compact.
+  - Using `--global-budget` may truncate or omit entire files to respect the total budget.
+  - The tool finds the largest preview that fits the budget; if even the tiniest preview exceeds it, you still get a minimal, valid preview.
+  - When passing file paths, directories and binary files are ignored; a notice is printed to stderr for each (e.g., `Ignored binary file: ./path/to/file`). Stdin mode reads the stream as-is.
+
+Quick one‑liners:
+
+- Peek a big JSON stream (keeps structure):
+
+      zstdcat huge.json.zst | headson -n 800 -f pseudo
+
+- Many files with a fixed overall size:
+
+      headson -N 1200 -f json logs/*.json
+
+- Glance at a file, JavaScript‑style comments for omissions:
+
+      headson -n 400 -f js data.json
+
+Show help:
+
+    headson --help
+
+## Examples: head vs headson
+
+Input:
+
+```json
+{"users":[{"id":1,"name":"Ana","roles":["admin","dev"]},{"id":2,"name":"Bo"}],"meta":{"count":2,"source":"db"}}
+```
+
+Naive cut (can break mid‑token):
+
+```bash
+jq -c . users.json | head -c 80
+# {"users":[{"id":1,"name":"Ana","roles":["admin","dev"]},{"id":2,"name":"Bo"}],"me
+```
+
+Structured preview with headson (pseudo):
+
+```bash
+headson -n 120 -f pseudo users.json
+# {
+#   users: [
+#     { id: 1, name: "Ana", roles: [ "admin", … ] },
+#     …
+#   ]
+#   meta: { count: 2, … }
+# }
+```
+
+Machine‑readable preview (json):
+
+```bash
+headson -n 120 -f json users.json
+# {"users":[{"id":1,"name":"Ana","roles":["admin"]}],"meta":{"count":2}}
+```
+
+## Python Bindings
+
+A thin Python extension module is available on PyPI as `headson`.
+
+ - Install: `pip install headson` (ABI3 wheels for Python 3.10+ on Linux/macOS/Windows).
+- API:
+  - `headson.summarize(text: str, *, template: str = "pseudo", character_budget: int | None = None, tail: bool = False) -> str`
+    - `template`: one of `"json" | "pseudo" | "js"`
+    - `character_budget`: maximum output size in characters (default: 500)
+  - `tail`: prefer the end of arrays when truncating; strings unaffected. Affects only display templates (`pseudo`/`js`); `json` remains strict.
+
+Example:
+
+```python
+import json
+import headson
+
+data = {"foo": [1, 2, 3], "bar": {"x": "y"}}
+preview = headson.summarize(json.dumps(data), template="json", character_budget=200)
+print(preview)
+
+# Prefer the tail of arrays (annotations show in pseudo/js only)
+print(
+    headson.summarize(
+        json.dumps(list(range(100))),
+        template="pseudo",
+        character_budget=80,
+        tail=True,
+    )
+)
+```
+
+## License
+
+MIT
+

headson-0.4.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+headson-0.4.0.dist-info/METADATA,sha256=R2xwoSZ2KhkXVMmqa8Bqlh8i_DjR3KzSLH8f0rfkS58,6015
+headson-0.4.0.dist-info/WHEEL,sha256=4EDp_7DiFfWl1yYv5M4wSosAn5L_xgD1dyrQxQxfCx8,95
+headson-0.4.0.dist-info/licenses/LICENSE,sha256=85XxIce4vPe2JysuORWOYpzGI-ypir_79W6aOF8y534,1093
+headson/__init__.py,sha256=PnXEkHuT6aEqKi8lL11uZU2IZ5cGgFqfO43xShmpros,137
+headson/headson.pyd,sha256=yywJ7fyfJ95heJpIjcJN53K_RLDAIQzzlvjlWB3RiY0,453632
+headson-0.4.0.dist-info/RECORD,,

headson-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.9.6)
+Root-Is-Purelib: false
+Tag: cp310-abi3-win_amd64

headson-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dániel Kántor
+
+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.