headson 0.6.4__tar.gz → 0.6.5__tar.gz

{headson-0.6.4 → headson-0.6.5}/Cargo.lock

@@ -298,7 +298,7 @@ dependencies = [
 
 [[package]]
 name = "headson"
-version = "0.6.4"
+version = "0.6.5"
 dependencies = [
  "anyhow",
  "assert_cmd",

{headson-0.6.4 → headson-0.6.5}/Cargo.toml

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

{headson-0.6.4 → headson-0.6.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: headson
-Version: 0.6.4
+Version: 0.6.5
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Rust
@@ -20,7 +20,7 @@ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
   <br/>
 </p>
 
-`heal`/`tail` for JSON, YAML - but structure‑aware. Get a compact preview that shows both the shape and representative values of your data, all within a strict character budget. (Just like `head`/`tail`, `headson` can also work with unstructured text files.)
+`heal`/`tail` for JSON, YAML - but structure‑aware. Get a compact preview that shows both the shape and representative values of your data, all within a strict byte budget. (Just like `head`/`tail`, `headson` can also work with unstructured text files.)
 
 Available as:
 - CLI (see [Usage](#usage))
@@ -190,11 +190,11 @@ 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, *, format: str = "auto", style: str = "default", input_format: str = "json", character_budget: int | None = None, skew: str = "balanced") -> str`
+  - `headson.summarize(text: str, *, format: str = "auto", style: str = "default", input_format: str = "json", byte_budget: int | None = None, skew: str = "balanced") -> str`
     - `format`: `"auto" | "json" | "yaml"` (auto maps to JSON family for single inputs)
     - `style`: `"strict" | "default" | "detailed"`
     - `input_format`: `"json" | "yaml"` (ingestion)
-    - `character_budget`: maximum output size in characters (default: 500)
+    - `byte_budget`: maximum output size in bytes (default: 500)
     - `skew`: `"balanced" | "head" | "tail"` (affects display styles; strict JSON remains unannotated)
 
 Examples:
@@ -204,7 +204,7 @@ import json
 import headson
 
 data = {"foo": [1, 2, 3], "bar": {"x": "y"}}
-preview = headson.summarize(json.dumps(data), format="json", style="strict", character_budget=200)
+preview = headson.summarize(json.dumps(data), format="json", style="strict", byte_budget=200)
 print(preview)
 
 # Prefer the tail of arrays (annotations show with style="default"/"detailed")
@@ -213,14 +213,14 @@ print(
         json.dumps(list(range(100))),
         format="json",
         style="detailed",
-        character_budget=80,
+        byte_budget=80,
         skew="tail",
     )
 )
 
 # YAML support
 doc = "root:\n  items: [1,2,3,4,5,6,7,8,9,10]\n"
-print(headson.summarize(doc, format="yaml", style="default", input_format="yaml", character_budget=60))
+print(headson.summarize(doc, format="yaml", style="default", input_format="yaml", byte_budget=60))
 ```
 
 # Algorithm
@@ -230,7 +230,7 @@ print(headson.summarize(doc, format="yaml", style="default", input_format="yaml"
 ## Footnotes
  - <sup><b>[1]</b></sup> <b>Optimized tree representation</b>: An arena‑style tree stored in flat, contiguous buffers. Each node records its kind and value plus index ranges into shared child and key arrays. Arrays are ingested in a single pass and may be deterministically pre‑sampled: the first element is always kept; additional elements are selected via a fixed per‑index inclusion test; for kept elements, original indices are stored and full lengths are counted. This enables accurate omission info and internal gap markers later, while minimizing pointer chasing.
  - <sup><b>[2]</b></sup> <b>Priority order</b>: Nodes are scored so previews surface representative structure and values first. Arrays can favor head/mid/tail coverage (default) or strictly the head; tail preference flips head/tail when configured. Object properties are ordered by key, and strings expand by grapheme with early characters prioritized over very deep expansions.
- - <sup><b>[3]</b></sup> <b>Choose top N nodes (binary search)</b>: Iteratively picks N so that the rendered preview fits within the character budget, looping between “choose N” and a render attempt to converge quickly.
+ - <sup><b>[3]</b></sup> <b>Choose top N nodes (binary search)</b>: Iteratively picks N so that the rendered preview fits within the byte budget, looping between “choose N” and a render attempt to converge quickly.
  - <sup><b>[4]</b></sup> <b>Render attempt</b>: Serializes the currently included nodes using the selected template. Omission summaries and per-file section headers appear in display templates (pseudo/js); json remains strict. For arrays, display templates may insert internal gap markers between non‑contiguous kept items using original indices.
  - <sup><b>[5]</b></sup> <b>Diagram source</b>: The Algorithm diagram is generated from `docs/diagrams/algorithm.mmd`. Regenerate the SVG with `cargo make diagrams` before releasing.
 

{headson-0.6.4 → headson-0.6.5}/README.md

@@ -6,7 +6,7 @@
   <br/>
 </p>
 
-`heal`/`tail` for JSON, YAML - but structure‑aware. Get a compact preview that shows both the shape and representative values of your data, all within a strict character budget. (Just like `head`/`tail`, `headson` can also work with unstructured text files.)
+`heal`/`tail` for JSON, YAML - but structure‑aware. Get a compact preview that shows both the shape and representative values of your data, all within a strict byte budget. (Just like `head`/`tail`, `headson` can also work with unstructured text files.)
 
 Available as:
 - CLI (see [Usage](#usage))
@@ -176,11 +176,11 @@ 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, *, format: str = "auto", style: str = "default", input_format: str = "json", character_budget: int | None = None, skew: str = "balanced") -> str`
+  - `headson.summarize(text: str, *, format: str = "auto", style: str = "default", input_format: str = "json", byte_budget: int | None = None, skew: str = "balanced") -> str`
     - `format`: `"auto" | "json" | "yaml"` (auto maps to JSON family for single inputs)
     - `style`: `"strict" | "default" | "detailed"`
     - `input_format`: `"json" | "yaml"` (ingestion)
-    - `character_budget`: maximum output size in characters (default: 500)
+    - `byte_budget`: maximum output size in bytes (default: 500)
     - `skew`: `"balanced" | "head" | "tail"` (affects display styles; strict JSON remains unannotated)
 
 Examples:
@@ -190,7 +190,7 @@ import json
 import headson
 
 data = {"foo": [1, 2, 3], "bar": {"x": "y"}}
-preview = headson.summarize(json.dumps(data), format="json", style="strict", character_budget=200)
+preview = headson.summarize(json.dumps(data), format="json", style="strict", byte_budget=200)
 print(preview)
 
 # Prefer the tail of arrays (annotations show with style="default"/"detailed")
@@ -199,14 +199,14 @@ print(
         json.dumps(list(range(100))),
         format="json",
         style="detailed",
-        character_budget=80,
+        byte_budget=80,
         skew="tail",
     )
 )
 
 # YAML support
 doc = "root:\n  items: [1,2,3,4,5,6,7,8,9,10]\n"
-print(headson.summarize(doc, format="yaml", style="default", input_format="yaml", character_budget=60))
+print(headson.summarize(doc, format="yaml", style="default", input_format="yaml", byte_budget=60))
 ```
 
 # Algorithm
@@ -216,7 +216,7 @@ print(headson.summarize(doc, format="yaml", style="default", input_format="yaml"
 ## Footnotes
  - <sup><b>[1]</b></sup> <b>Optimized tree representation</b>: An arena‑style tree stored in flat, contiguous buffers. Each node records its kind and value plus index ranges into shared child and key arrays. Arrays are ingested in a single pass and may be deterministically pre‑sampled: the first element is always kept; additional elements are selected via a fixed per‑index inclusion test; for kept elements, original indices are stored and full lengths are counted. This enables accurate omission info and internal gap markers later, while minimizing pointer chasing.
  - <sup><b>[2]</b></sup> <b>Priority order</b>: Nodes are scored so previews surface representative structure and values first. Arrays can favor head/mid/tail coverage (default) or strictly the head; tail preference flips head/tail when configured. Object properties are ordered by key, and strings expand by grapheme with early characters prioritized over very deep expansions.
- - <sup><b>[3]</b></sup> <b>Choose top N nodes (binary search)</b>: Iteratively picks N so that the rendered preview fits within the character budget, looping between “choose N” and a render attempt to converge quickly.
+ - <sup><b>[3]</b></sup> <b>Choose top N nodes (binary search)</b>: Iteratively picks N so that the rendered preview fits within the byte budget, looping between “choose N” and a render attempt to converge quickly.
  - <sup><b>[4]</b></sup> <b>Render attempt</b>: Serializes the currently included nodes using the selected template. Omission summaries and per-file section headers appear in display templates (pseudo/js); json remains strict. For arrays, display templates may insert internal gap markers between non‑contiguous kept items using original indices.
  - <sup><b>[5]</b></sup> <b>Diagram source</b>: The Algorithm diagram is generated from `docs/diagrams/algorithm.mmd`. Regenerate the SVG with `cargo make diagrams` before releasing.
 

{headson-0.6.4 → headson-0.6.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "headson"
-version = "0.6.4"
+version = "0.6.5"
 description = "Budget‑constrained JSON preview renderer (Python bindings)"
 readme = "README.md"
 requires-python = ">=3.10"

{headson-0.6.4 → headson-0.6.5}/python/Cargo.lock

@@ -214,7 +214,7 @@ dependencies = [
 
 [[package]]
 name = "headson"
-version = "0.6.4"
+version = "0.6.5"
 dependencies = [
  "anyhow",
  "clap",
@@ -228,7 +228,7 @@ dependencies = [
 
 [[package]]
 name = "headson-python"
-version = "0.6.4"
+version = "0.6.5"
 dependencies = [
  "anyhow",
  "headson",

{headson-0.6.4 → headson-0.6.5}/python/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "headson-python"
-version = "0.6.4"
+version = "0.6.5"
 edition = "2021"
 publish = false
 readme = "README.md"

{headson-0.6.4 → headson-0.6.5}/python/README.md

@@ -4,11 +4,11 @@ Minimal Python API for the `headson` preview renderer.
 
 API
 
-- `headson.summarize(text: str, *, format: str = "auto", style: str = "default", input_format: str = "json", character_budget: int | None = None, skew: str = "balanced") -> str`
+- `headson.summarize(text: str, *, format: str = "auto", style: str = "default", input_format: str = "json", byte_budget: int | None = None, skew: str = "balanced") -> str`
   - `format`: output format — `"auto" | "json" | "yaml" | "text"`.
   - `style`: output style — `"strict" | "default" | "detailed"`.
   - `input_format`: ingestion format — `"json" | "yaml" | "text"`.
-  - `character_budget`: maximum output size in characters (defaults to 500 if not set).
+  - `byte_budget`: maximum output size in bytes (defaults to 500 if not set).
   - `skew`: one of `"balanced" | "head" | "tail"`.
     - `balanced` (default), `head` keeps first N, `tail` keeps last N. Display styles place omission markers accordingly; strict JSON remains unannotated.
   - Notes:
@@ -20,26 +20,26 @@ Examples:
 import headson
 
 # Human-friendly JSON (Pseudo) with a small budget
-print(headson.summarize('{"a": 1, "b": [1,2,3]}', format="json", style="default", character_budget=80))
+print(headson.summarize('{"a": 1, "b": [1,2,3]}', format="json", style="default", byte_budget=80))
 
 # Strict JSON stays valid JSON
-print(headson.summarize('{"a": 1, "b": {"c": 2}}', format="json", style="strict", character_budget=10_000))
+print(headson.summarize('{"a": 1, "b": {"c": 2}}', format="json", style="strict", byte_budget=10_000))
 
 # Annotated JSON (JS) with tail skew: prefer the end of arrays when truncating
 arr = ','.join(str(i) for i in range(100))
-print(headson.summarize('{"arr": [' + arr + ']}', format="json", style="detailed", character_budget=60, skew="tail"))
+print(headson.summarize('{"arr": [' + arr + ']}', format="json", style="detailed", byte_budget=60, skew="tail"))
 
 # YAML styles: strict (no comments), default (… comments), detailed (counts)
 doc = 'root:\n  items: [1,2,3,4,5,6,7,8,9,10]\n'
-print(headson.summarize(doc, format="yaml", style="strict", input_format="yaml", character_budget=60))
-print(headson.summarize(doc, format="yaml", style="default", input_format="yaml", character_budget=60))
-print(headson.summarize(doc, format="yaml", style="detailed", input_format="yaml", character_budget=60))
+print(headson.summarize(doc, format="yaml", style="strict", input_format="yaml", byte_budget=60))
+print(headson.summarize(doc, format="yaml", style="default", input_format="yaml", byte_budget=60))
+print(headson.summarize(doc, format="yaml", style="detailed", input_format="yaml", byte_budget=60))
 
 # Note: tail mode affects only display styles; strict JSON stays strict.
 
 # Text: render raw lines with omission markers depending on style
 text = "one\ntwo\nthree\n"
-print(headson.summarize(text, format="text", style="default", input_format="text", character_budget=10))
+print(headson.summarize(text, format="text", style="default", input_format="text", byte_budget=10))
 ```
 
 Install for development:

{headson-0.6.4 → headson-0.6.5}/python/src/lib.rs

@@ -59,6 +59,7 @@ fn render_config_with_sampler(
         color_mode: ColorMode::Auto,
         color_enabled: false,
         style: s,
+        string_free_prefix_graphemes: None,
     })
 }
 
@@ -85,6 +86,7 @@ fn priority_config(
         prefer_tail_arrays,
         array_bias: headson_core::ArrayBias::HeadMidTail,
         array_sampler: sampler,
+        line_budget_only: false,
     }
 }
 
@@ -93,19 +95,19 @@ fn to_pyerr(e: anyhow::Error) -> PyErr {
 }
 
 #[pyfunction]
-#[pyo3(signature = (text, *, format="auto", style="default", character_budget=None, skew="balanced", input_format="json"))]
+#[pyo3(signature = (text, *, format="auto", style="default", byte_budget=None, skew="balanced", input_format="json"))]
 fn summarize(
     py: Python<'_>,
     text: &str,
     format: &str,
     style: &str,
-    character_budget: Option<usize>,
+    byte_budget: Option<usize>,
     skew: &str,
     input_format: &str,
 ) -> PyResult<String> {
     let sampler = parse_skew(skew).map_err(to_pyerr)?;
     let cfg = render_config_with_sampler(format, style, sampler).map_err(to_pyerr)?;
-    let budget = character_budget.unwrap_or(500);
+    let budget = byte_budget.unwrap_or(500);
     let per_file_for_priority = budget.max(1);
     let prio = priority_config(per_file_for_priority, sampler);
     let input = text.as_bytes().to_vec();

{headson-0.6.4 → headson-0.6.5}/src/ingest/formats/text/mod.rs

@@ -220,6 +220,7 @@ mod tests {
             color_mode: crate::serialization::types::ColorMode::Off,
             color_enabled: false,
             style: Style::Default,
+            string_free_prefix_graphemes: None,
         };
         let prio = PriorityConfig::new(100, 100);
         (cfg, prio)

{headson-0.6.4 → headson-0.6.5}/src/lib.rs

@@ -35,6 +35,12 @@ pub use serialization::types::{
     ColorMode, OutputTemplate, RenderConfig, Style,
 };
 
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
+pub struct Budgets {
+    pub byte_budget: Option<usize>,
+    pub line_budget: Option<usize>,
+}
+
 pub fn headson(
     input: Vec<u8>,
     config: &RenderConfig,
@@ -43,7 +49,14 @@ pub fn headson(
 ) -> Result<String> {
     let arena = crate::ingest::parse_json_one(input, priority_cfg)?;
     let order_build = order::build_order(&arena, priority_cfg)?;
-    let out = find_largest_render_under_budget(&order_build, config, budget);
+    let out = find_largest_render_under_budgets(
+        &order_build,
+        config,
+        Budgets {
+            byte_budget: Some(budget),
+            line_budget: None,
+        },
+    );
     Ok(out)
 }
 
@@ -55,7 +68,14 @@ pub fn headson_many(
 ) -> Result<String> {
     let arena = crate::ingest::parse_json_many(inputs, priority_cfg)?;
     let order_build = order::build_order(&arena, priority_cfg)?;
-    let out = find_largest_render_under_budget(&order_build, config, budget);
+    let out = find_largest_render_under_budgets(
+        &order_build,
+        config,
+        Budgets {
+            byte_budget: Some(budget),
+            line_budget: None,
+        },
+    );
     Ok(out)
 }
 
@@ -68,7 +88,14 @@ pub fn headson_yaml(
 ) -> Result<String> {
     let arena = crate::ingest::parse_yaml_one(input, priority_cfg)?;
     let order_build = order::build_order(&arena, priority_cfg)?;
-    let out = find_largest_render_under_budget(&order_build, config, budget);
+    let out = find_largest_render_under_budgets(
+        &order_build,
+        config,
+        Budgets {
+            byte_budget: Some(budget),
+            line_budget: None,
+        },
+    );
     Ok(out)
 }
 
@@ -81,7 +108,14 @@ pub fn headson_many_yaml(
 ) -> Result<String> {
     let arena = crate::ingest::parse_yaml_many(inputs, priority_cfg)?;
     let order_build = order::build_order(&arena, priority_cfg)?;
-    let out = find_largest_render_under_budget(&order_build, config, budget);
+    let out = find_largest_render_under_budgets(
+        &order_build,
+        config,
+        Budgets {
+            byte_budget: Some(budget),
+            line_budget: None,
+        },
+    );
     Ok(out)
 }
 
@@ -94,7 +128,14 @@ pub fn headson_text(
 ) -> Result<String> {
     let arena = crate::ingest::parse_text_one(input, priority_cfg)?;
     let order_build = order::build_order(&arena, priority_cfg)?;
-    let out = find_largest_render_under_budget(&order_build, config, budget);
+    let out = find_largest_render_under_budgets(
+        &order_build,
+        config,
+        Budgets {
+            byte_budget: Some(budget),
+            line_budget: None,
+        },
+    );
     Ok(out)
 }
 
@@ -107,31 +148,44 @@ pub fn headson_many_text(
 ) -> Result<String> {
     let arena = crate::ingest::parse_text_many(inputs, priority_cfg)?;
     let order_build = order::build_order(&arena, priority_cfg)?;
-    let out = find_largest_render_under_budget(&order_build, config, budget);
+    let out = find_largest_render_under_budgets(
+        &order_build,
+        config,
+        Budgets {
+            byte_budget: Some(budget),
+            line_budget: None,
+        },
+    );
     Ok(out)
 }
 
-fn find_largest_render_under_budget(
+/// New generalized budgeting: enforce optional char and/or line caps.
+fn find_largest_render_under_budgets(
     order_build: &PriorityOrder,
     config: &RenderConfig,
-    char_budget: usize,
+    budgets: Budgets,
 ) -> String {
     // Binary search the largest k in [1, total] whose render
-    // fits within `char_budget`.
+    // fits within all requested budgets.
     let total = order_build.total_nodes;
     if total == 0 {
         return String::new();
     }
     // Each included node contributes at least some output; cap hi by budget.
     let lo = 1usize;
-    let hi = total.min(char_budget.max(1));
+    // For the upper bound, when a byte budget is present, we can safely cap by it;
+    // otherwise, cap by total.
+    let hi = match budgets.byte_budget {
+        Some(c) => total.min(c.max(1)),
+        None => total,
+    };
     // 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;
     // Measure length without color so ANSI escapes do not count toward the
-    // character budget. Then render once more with the requested color setting.
+    // byte budget. Then render once more with the requested color setting.
     let mut best_k: Option<usize> = None;
     let mut measure_cfg = config.clone();
     measure_cfg.color_enabled = false;
@@ -145,7 +199,12 @@ fn find_largest_render_under_budget(
             &measure_cfg,
         );
         render_set_id = render_set_id.wrapping_add(1).max(1);
-        if s.len() <= char_budget {
+        // Measure output using a unified stats helper and enforce
+        // all provided caps (chars and/or lines).
+        let stats = crate::utils::measure::count_output_stats(&s);
+        let fits_chars = budgets.byte_budget.is_none_or(|c| stats.bytes <= c);
+        let fits_lines = budgets.line_budget.is_none_or(|l| stats.lines <= l);
+        if fits_chars && fits_lines {
             best_k = Some(mid);
             true
         } else {
@@ -174,3 +233,94 @@ fn find_largest_render_under_budget(
         )
     }
 }
+
+// Optional new public API that accepts both budgets explicitly.
+pub fn headson_with_budgets(
+    input: Vec<u8>,
+    config: &RenderConfig,
+    priority_cfg: &PriorityConfig,
+    budgets: Budgets,
+) -> Result<String> {
+    let arena = crate::ingest::parse_json_one(input, priority_cfg)?;
+    let order_build = order::build_order(&arena, priority_cfg)?;
+    Ok(find_largest_render_under_budgets(
+        &order_build,
+        config,
+        budgets,
+    ))
+}
+
+pub fn headson_many_with_budgets(
+    inputs: Vec<(String, Vec<u8>)>,
+    config: &RenderConfig,
+    priority_cfg: &PriorityConfig,
+    budgets: Budgets,
+) -> Result<String> {
+    let arena = crate::ingest::parse_json_many(inputs, priority_cfg)?;
+    let order_build = order::build_order(&arena, priority_cfg)?;
+    Ok(find_largest_render_under_budgets(
+        &order_build,
+        config,
+        budgets,
+    ))
+}
+
+pub fn headson_yaml_with_budgets(
+    input: Vec<u8>,
+    config: &RenderConfig,
+    priority_cfg: &PriorityConfig,
+    budgets: Budgets,
+) -> Result<String> {
+    let arena = crate::ingest::parse_yaml_one(input, priority_cfg)?;
+    let order_build = order::build_order(&arena, priority_cfg)?;
+    Ok(find_largest_render_under_budgets(
+        &order_build,
+        config,
+        budgets,
+    ))
+}
+
+pub fn headson_many_yaml_with_budgets(
+    inputs: Vec<(String, Vec<u8>)>,
+    config: &RenderConfig,
+    priority_cfg: &PriorityConfig,
+    budgets: Budgets,
+) -> Result<String> {
+    let arena = crate::ingest::parse_yaml_many(inputs, priority_cfg)?;
+    let order_build = order::build_order(&arena, priority_cfg)?;
+    Ok(find_largest_render_under_budgets(
+        &order_build,
+        config,
+        budgets,
+    ))
+}
+
+pub fn headson_text_with_budgets(
+    input: Vec<u8>,
+    config: &RenderConfig,
+    priority_cfg: &PriorityConfig,
+    budgets: Budgets,
+) -> Result<String> {
+    let arena = crate::ingest::parse_text_one(input, priority_cfg)?;
+    let order_build = order::build_order(&arena, priority_cfg)?;
+    Ok(find_largest_render_under_budgets(
+        &order_build,
+        config,
+        budgets,
+    ))
+}
+
+pub fn headson_many_text_with_budgets(
+    inputs: Vec<(String, Vec<u8>)>,
+    config: &RenderConfig,
+    priority_cfg: &PriorityConfig,
+    budgets: Budgets,
+) -> Result<String> {
+    let arena = crate::ingest::parse_text_many(inputs, priority_cfg)?;
+    let order_build = order::build_order(&arena, priority_cfg)?;
+    Ok(find_largest_render_under_budgets(
+        &order_build,
+        config,
+        budgets,
+    ))
+}