headson 0.2.5__tar.gz → 0.4.0__tar.gz

{headson-0.2.5 → headson-0.4.0}/Cargo.lock

@@ -266,7 +266,7 @@ dependencies = [
 
 [[package]]
 name = "headson"
-version = "0.2.5"
+version = "0.4.0"
 dependencies = [
  "anyhow",
  "assert_cmd",

{headson-0.2.5 → headson-0.4.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "headson"
-version = "0.2.5"
+version = "0.4.0"
 edition = "2024"
 description = "Budget‑constrained JSON preview renderer"
 readme = "README.md"

headson-0.4.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,153 @@
+# 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.2.5 → headson-0.4.0}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "maturin"
 
 [project]
 name = "headson"
-version = "0.2.5"
+version = "0.4.0"
 description = "Budget‑constrained JSON preview renderer (Python bindings)"
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.10"
 classifiers = [
   "Programming Language :: Python",
   "Programming Language :: Python :: 3",
@@ -32,7 +32,7 @@ python-source = "python"
 dev = [
   "pytest>=8",
   "maturin>=1.7,<2",
-  "ruff>=0.6",
+  "ruff==0.14.2",
 ]
 
 [tool.ruff]
@@ -42,5 +42,3 @@ src = ["python", "tests_py"]
 
 [tool.ruff.lint]
 select = ["E", "F"]
-
- 

{headson-0.2.5 → headson-0.4.0}/python/Cargo.lock

@@ -169,7 +169,7 @@ dependencies = [
 
 [[package]]
 name = "headson"
-version = "0.2.5"
+version = "0.4.0"
 dependencies = [
  "anyhow",
  "clap",
@@ -182,7 +182,7 @@ dependencies = [
 
 [[package]]
 name = "headson-python"
-version = "0.2.5"
+version = "0.4.0"
 dependencies = [
  "anyhow",
  "headson",

{headson-0.2.5 → headson-0.4.0}/python/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "headson-python"
-version = "0.2.5"
+version = "0.4.0"
 edition = "2021"
 publish = false
 readme = "README.md"
@@ -11,5 +11,5 @@ crate-type = ["cdylib"]
 
 [dependencies]
 anyhow = "1"
-pyo3 = { version = "0.27", features = ["extension-module"] }
+pyo3 = { version = "0.27", features = ["extension-module", "abi3-py310"] }
 headson_core = { package = "headson", path = ".." }

{headson-0.2.5 → headson-0.4.0}/python/README.md

@@ -4,19 +4,27 @@ Minimal Python API for the `headson` JSON preview renderer.
 
 Currently exported function:
 
-- `headson.summarize(text: str, *, template: str = "pseudo", character_budget: int | None = None) -> str`
+- `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 (defaults to 500 if not set).
+  - `tail`: prefer the end of arrays when truncating; strings are unaffected. Only affects display templates (`pseudo`/`js`); `json` remains strict JSON with no annotations.
 
 Examples:
 
 ```python
 import headson
 
+# Pseudo template with a small budget (structure-aware preview)
 print(headson.summarize('{"a": 1, "b": [1,2,3]}', template="pseudo", character_budget=80))
+
+# Strict JSON template preserves valid JSON output
 print(headson.summarize('{"a": 1, "b": {"c": 2}}', template="json", character_budget=10_000))
+
+# JS template with tail preference: prefer the end of arrays when truncating
 arr = ','.join(str(i) for i in range(100))
-print(headson.summarize('{"arr": [' + arr + ']}', template="js", character_budget=60))
+print(headson.summarize('{"arr": [' + arr + ']}', template="js", character_budget=60, tail=True))
+
+# Note: tail mode affects only pseudo/js display templates; the json template stays strict.
 ```
 
 Install for development:

{headson-0.2.5 → headson-0.4.0}/python/src/lib.rs

@@ -13,9 +13,7 @@ fn to_template(s: &str) -> Result<OutputTemplate> {
     }
 }
 
-fn render_config(
-    template: &str,
-) -> Result<RenderConfig> {
+fn render_config(template: &str, prefer_tail_arrays: bool) -> Result<RenderConfig> {
     let t = to_template(template)?;
     let space = " ".to_string();
     let newline = "\n".to_string();
@@ -25,13 +23,15 @@ fn render_config(
         indent_unit,
         space,
         newline,
+        prefer_tail_arrays,
     })
 }
 
-fn priority_config(per_file_budget: usize) -> PriorityConfig {
+fn priority_config(per_file_budget: usize, prefer_tail_arrays: bool) -> PriorityConfig {
     PriorityConfig {
         max_string_graphemes: 500,
         array_max_items: (per_file_budget / 2).max(1),
+        prefer_tail_arrays,
     }
 }
 
@@ -40,17 +40,18 @@ fn to_pyerr(e: anyhow::Error) -> PyErr {
 }
 
 #[pyfunction]
-#[pyo3(signature = (text, *, template="pseudo", character_budget=None))]
+#[pyo3(signature = (text, *, template="pseudo", character_budget=None, tail=false))]
 fn summarize(
     py: Python<'_>,
     text: &str,
     template: &str,
     character_budget: Option<usize>,
+    tail: bool,
 ) -> PyResult<String> {
-    let cfg = render_config(template).map_err(to_pyerr)?;
+    let cfg = render_config(template, tail).map_err(to_pyerr)?;
     let budget = character_budget.unwrap_or(500);
     let per_file_for_priority = budget.max(1);
-    let prio = priority_config(per_file_for_priority);
+    let prio = priority_config(per_file_for_priority, tail);
     let input = text.as_bytes().to_vec();
     py.detach(|| headson_core::headson(input, &cfg, &prio, budget).map_err(to_pyerr))
 }

{headson-0.2.5 → headson-0.4.0}/src/lib.rs

@@ -70,20 +70,22 @@ fn find_largest_render_under_budget(
     // Each included node contributes at least some output; cap hi by budget.
     let lo = 1usize;
     let hi = total.min(char_budget.max(1));
-    // Reusable inclusion marks to avoid clearing per probe
-    let mut marks: Vec<u32> = vec![0; total];
-    let mut mark_gen: u32 = 1;
+    // Reuse render-inclusion flags across render attempts to avoid clearing the vector.
+    // A node participates in the current render attempt when inclusion_flags[id] == render_set_id.
+    let mut inclusion_flags: Vec<u32> = vec![0; total];
+    // Each render attempt bumps this non-zero identifier to create a fresh inclusion set.
+    let mut render_set_id: u32 = 1;
     let mut best_str: Option<String> = None;
 
     let _ = crate::utils::search::binary_search_max(lo, hi, |mid| {
-        let s = crate::serialization::render_arena_with_marks(
+        let s = crate::serialization::render_top_k(
             order_build,
             mid,
-            &mut marks,
-            mark_gen,
+            &mut inclusion_flags,
+            render_set_id,
             config,
         );
-        mark_gen = mark_gen.wrapping_add(1).max(1);
+        render_set_id = render_set_id.wrapping_add(1).max(1);
         if s.len() <= char_budget {
             best_str = Some(s);
             true
@@ -97,11 +99,11 @@ fn find_largest_render_under_budget(
     } else {
         // Fallback: always render a single node (k=1) to produce the
         // shortest possible preview, even if it exceeds the byte budget.
-        crate::serialization::render_arena_with_marks(
+        crate::serialization::render_top_k(
             order_build,
             1,
-            &mut marks,
-            mark_gen,
+            &mut inclusion_flags,
+            render_set_id,
             config,
         )
     }

{headson-0.2.5 → headson-0.4.0}/src/main.rs

@@ -53,6 +53,12 @@ struct Cli {
         help = "Total output budget across all inputs; useful to keep multiple files within a fixed overall output size (may omit entire files)."
     )]
     global_budget: Option<usize>,
+    #[arg(
+        long = "tail",
+        default_value_t = false,
+        help = "Prefer the end of arrays when truncating. Strings unaffected; JSON stays strict."
+    )]
+    tail: bool,
     #[arg(
         value_name = "INPUT",
         value_hint = clap::ValueHint::FilePath,
@@ -225,6 +231,7 @@ fn get_render_config_from(cli: &Cli) -> headson::RenderConfig {
         indent_unit,
         space,
         newline,
+        prefer_tail_arrays: cli.tail,
     }
 }
 
@@ -232,14 +239,9 @@ fn get_priority_config(
     per_file_budget: usize,
     cli: &Cli,
 ) -> headson::PriorityConfig {
-    // Optimization: derive a conservative per‑array expansion cap from the output
-    // budget to avoid allocating/walking items that could never appear in the
-    // final preview. As a simple lower bound, an array of N items needs ~2*N
-    // bytes to render (item plus comma), so we cap per‑array expansion at
-    // budget/2. This prunes unnecessary work on large inputs without changing
-    // output semantics.
     headson::PriorityConfig {
         max_string_graphemes: cli.string_cap,
         array_max_items: (per_file_budget / 2).max(1),
+        prefer_tail_arrays: cli.tail,
     }
 }