headson 0.4.0__cp310-abi3-macosx_11_0_arm64.whl → 0.5.1__cp310-abi3-macosx_11_0_arm64.whl

headson/__init__.py

@@ -1,4 +1,6 @@
-# Re-export the public API from the compiled extension submodule
+from __future__ import annotations
+
+# Directly re-export the compiled extension function with the final signature.
 from .headson import summarize  # type: ignore
 
 __all__ = ["summarize"]

{headson-0.4.0.dist-info → headson-0.5.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: headson
-Version: 0.4.0
+Version: 0.5.1
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Rust
@@ -66,7 +66,8 @@ Common flags:
 - `--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.
+- `--head`: prefer the beginning of arrays when truncating (keep first N). Strings are unaffected. In `pseudo`/`js` templates the omission marker appears near the end; `json` remains strict. Mutually exclusive with `--tail`.
+- `--tail`: prefer the end of arrays when truncating (keep last N). Strings are unaffected. In `pseudo`/`js` templates the omission marker appears at the start; `json` remains strict. Mutually exclusive with `--head`.
 
 Notes:
 
@@ -77,6 +78,7 @@ Notes:
   - 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.
+  - Head vs Tail sampling: these options bias which part of arrays are kept before rendering. They guarantee the kept segment is contiguous at the chosen side (prefix for `--head`, suffix for `--tail`). Display templates may still insert additional internal gap markers inside that kept segment to honor very small budgets; `json` remains strict and unannotated.
 
 Quick one‑liners:
 
@@ -137,10 +139,10 @@ 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`
+  - `headson.summarize(text: str, *, template: str = "pseudo", character_budget: int | None = None, skew: str = "balanced") -> 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.
+    - `skew`: one of `"balanced" | "head" | "tail"` (focus arrays on start vs end; only affects display templates; `json` remains strict).
 
 Example:
 
@@ -158,11 +160,56 @@ print(
         json.dumps(list(range(100))),
         template="pseudo",
         character_budget=80,
-        tail=True,
+        skew="tail",
     )
 )
 ```
 
+# Algorithm
+
+```mermaid
+%%{init: {"themeCSS": ".cluster > rect { fill: transparent; stroke: transparent; } .clusterLabel > text { font-size: 16px; font-weight: 600; } .clusterLabel span { padding: 6px 10px; font-size: 16px; font-weight: 600; }"}}%%
+flowchart TD
+    subgraph Deserialization
+        direction TB
+        A["Input file(s)"]
+        A -- Single --> C["Parse into optimized tree (with array pre‑sampling) ¹"]
+        A -- Multiple --> D["Parse each file and wrap into a fileset object"]
+        D --> C
+    end
+    subgraph Prioritization
+        direction TB
+        E["Build priority order ²"]
+        F["Choose top N nodes ³"]
+    end
+    subgraph Serialization
+        direction TB
+        G["Render attempt ⁴"]
+        H["Output preview string"]
+    end
+    C --> E
+    E --> F
+    F --> G
+    G --> F
+    F --> H
+    %% Color classes for categories
+    classDef des fill:#eaf2ff,stroke:#3b82f6,stroke-width:1px,color:#0f172a;
+    classDef prio fill:#ecfdf5,stroke:#10b981,stroke-width:1px,color:#064e3b;
+    classDef ser fill:#fff1f2,stroke:#f43f5e,stroke-width:1px,color:#7f1d1d;
+    class A,C,D des;
+    class E,F prio;
+    class G,H ser;
+    style Deserialization fill:transparent,stroke:transparent
+    style Prioritization fill:transparent,stroke:transparent
+    style Serialization fill:transparent,stroke:transparent
+```
+
+## 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>[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.
+
 ## License
 
 MIT

headson-0.5.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+headson-0.5.1.dist-info/METADATA,sha256=pv3wYywpSE8OuULv5-LgGycmOJi2kFukurzkLUGdyIY,9371
+headson-0.5.1.dist-info/WHEEL,sha256=-lwEpi49KOTCcgx48T3fLSP8Dxynwa-iRMZNo-JZaqc,103
+headson-0.5.1.dist-info/licenses/LICENSE,sha256=GZ9row3L2LsnOSbEuGMQZ0zKOIEd5tHr76cZHpg4KK8,1072
+headson/__init__.py,sha256=8DXFB8ahlywyQXJsscl3w_wgbcQi7sj7zEuV28wR60E,187
+headson/headson.abi3.so,sha256=IOPVBfgMnRLzVUeY-JHJAFOPnW-x_vP6aiskgtG6pcY,604752
+headson-0.5.1.dist-info/RECORD,,

headson-0.4.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-headson-0.4.0.dist-info/METADATA,sha256=ynLBqMBpx40wDmbk1JnRxLj1IIc6fM7MGgJTUnVFSpw,5862
-headson-0.4.0.dist-info/WHEEL,sha256=-lwEpi49KOTCcgx48T3fLSP8Dxynwa-iRMZNo-JZaqc,103
-headson-0.4.0.dist-info/licenses/LICENSE,sha256=GZ9row3L2LsnOSbEuGMQZ0zKOIEd5tHr76cZHpg4KK8,1072
-headson/__init__.py,sha256=PnXEkHuT6aEqKi8lL11uZU2IZ5cGgFqfO43xShmpros,137
-headson/headson.abi3.so,sha256=KB8ibXCt41RWTqa-ne-PNuJ3Y6ILMftQN4cU3_96yps,604944
-headson-0.4.0.dist-info/RECORD,,