headson 0.6.1__tar.gz → 0.6.3__tar.gz

{headson-0.6.1 → headson-0.6.3}/Cargo.lock

@@ -64,15 +64,20 @@ version = "1.0.100"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a23eb6b1614318a8071c9b2521f36b424b2c83db5eb3a0fead4a6c0809af6e61"
 
+[[package]]
+name = "arraydeque"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7d902e3d592a523def97af8f317b08ce16b7ab854c1985a0c671e6f15cebc236"
+
 [[package]]
 name = "assert_cmd"
-version = "2.0.17"
+version = "2.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2bd389a4b2970a01282ee455294913c0a43724daedcd1a24c3eb0ec1c1320b66"
+checksum = "bcbb6924530aa9e0432442af08bbcafdad182db80d2e560da42a6d442535bf85"
 dependencies = [
  "anstyle",
  "bstr",
- "doc-comment",
  "libc",
  "predicates",
  "predicates-core",
@@ -111,9 +116,9 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
 [[package]]
 name = "clap"
-version = "4.5.50"
+version = "4.5.51"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0c2cfd7bf8a6017ddaa4e32ffe7403d547790db06bd171c1c53926faab501623"
+checksum = "4c26d721170e0295f191a69bd9a1f93efcdb0aff38684b61ab5750468972e5f5"
 dependencies = [
  "clap_builder",
  "clap_derive",
@@ -121,9 +126,9 @@ dependencies = [
 
 [[package]]
 name = "clap_builder"
-version = "4.5.50"
+version = "4.5.51"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0a4c05b9e80c5ccd3a7ef080ad7b6ba7d6fc00a985b8b157197075677c82c7a0"
+checksum = "75835f0c7bf681bfd05abe44e965760fea999a5286c6eb2d59883634fd02011a"
 dependencies = [
  "anstream",
  "anstyle",
@@ -182,18 +187,21 @@ version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6184e33543162437515c2e2b48714794e37845ec9851711914eec9d308f6ebe8"
 
-[[package]]
-name = "doc-comment"
-version = "0.3.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fea41bba32d969b513997752735605054bc0dfa92b4c56bf1189f2e174be7a10"
-
 [[package]]
 name = "encode_unicode"
 version = "1.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "34aa73646ffb006b8f5147f3dc182bd4bcb190227ce861fc4a4844bf8e3cb2c0"
 
+[[package]]
+name = "encoding_rs"
+version = "0.8.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75030f3c4f45dafd7586dd6780965a8c7e8e285a5ecb86713e63a79c5b2766f3"
+dependencies = [
+ "cfg-if",
+]
+
 [[package]]
 name = "equivalent"
 version = "1.0.2"
@@ -207,7 +215,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
 dependencies = [
  "libc",
- "windows-sys 0.60.2",
+ "windows-sys 0.59.0",
 ]
 
 [[package]]
@@ -225,6 +233,12 @@ dependencies = [
  "num-traits",
 ]
 
+[[package]]
+name = "foldhash"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
+
 [[package]]
 name = "foldhash"
 version = "0.2.0"
@@ -249,10 +263,19 @@ version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0c7ed2f2edad8a14c8186b847909a41fbb9c3eafa44f88bd891114ed5019da09"
 dependencies = [
- "hashbrown",
+ "hashbrown 0.16.0",
  "serde",
 ]
 
+[[package]]
+name = "hashbrown"
+version = "0.15.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
+dependencies = [
+ "foldhash 0.1.5",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.16.0"
@@ -261,12 +284,21 @@ checksum = "5419bdc4f6a9207fbeba6d11b604d481addf78ecd10c11ad51e76c2f6482748d"
 dependencies = [
  "allocator-api2",
  "equivalent",
- "foldhash",
+ "foldhash 0.2.0",
+]
+
+[[package]]
+name = "hashlink"
+version = "0.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7382cf6263419f2d8df38c55d7da83da5c18aef87fc7a7fc1fb1e344edfe14c1"
+dependencies = [
+ "hashbrown 0.15.5",
 ]
 
 [[package]]
 name = "headson"
-version = "0.6.1"
+version = "0.6.3"
 dependencies = [
  "anyhow",
  "assert_cmd",
@@ -277,10 +309,12 @@ dependencies = [
  "rand_chacha",
  "serde",
  "serde_json",
+ "serde_yaml",
  "simd-json",
  "tempfile",
  "test_each_file",
  "unicode-segmentation",
+ "yaml-rust2",
 ]
 
 [[package]]
@@ -289,6 +323,16 @@ version = "0.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
 
+[[package]]
+name = "indexmap"
+version = "2.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6717a8d2a5a929a1a2eb43a12812498ed141a0bcfb7e8f7844fbdbe4303bba9f"
+dependencies = [
+ "equivalent",
+ "hashbrown 0.16.0",
+]
+
 [[package]]
 name = "insta"
 version = "1.43.2"
@@ -476,7 +520,7 @@ dependencies = [
  "errno",
  "libc",
  "linux-raw-sys",
- "windows-sys 0.60.2",
+ "windows-sys 0.59.0",
 ]
 
 [[package]]
@@ -528,6 +572,19 @@ dependencies = [
  "serde_core",
 ]
 
+[[package]]
+name = "serde_yaml"
+version = "0.9.34+deprecated"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6a8b1a1a2ebf674015cc02edccce75287f1a0130d394307b36743c2f5d504b47"
+dependencies = [
+ "indexmap",
+ "itoa",
+ "ryu",
+ "serde",
+ "unsafe-libyaml",
+]
+
 [[package]]
 name = "simd-json"
 version = "0.17.0"
@@ -581,7 +638,7 @@ dependencies = [
  "getrandom",
  "once_cell",
  "rustix",
- "windows-sys 0.60.2",
+ "windows-sys 0.59.0",
 ]
 
 [[package]]
@@ -614,6 +671,12 @@ version = "1.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f6ccf251212114b54433ec949fd6a7841275f9ada20dddd2f29e9ceea4501493"
 
+[[package]]
+name = "unsafe-libyaml"
+version = "0.2.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "673aac59facbab8a9007c7f6108d11f63b603f7cabff99fabf650fea5c32b861"
+
 [[package]]
 name = "utf8parse"
 version = "0.2.2"
@@ -809,6 +872,17 @@ version = "0.46.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f17a85883d4e6d00e8a97c586de764dabcc06133f7f1d55dce5cdc070ad7fe59"
 
+[[package]]
+name = "yaml-rust2"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2462ea039c445496d8793d052e13787f2b90e750b833afee748e601c17621ed9"
+dependencies = [
+ "arraydeque",
+ "encoding_rs",
+ "hashlink",
+]
+
 [[package]]
 name = "zerocopy"
 version = "0.8.27"

{headson-0.6.1 → headson-0.6.3}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "headson"
-version = "0.6.1"
+version = "0.6.3"
 edition = "2024"
 description = "Budget‑constrained JSON preview renderer"
 readme = "README.md"
@@ -27,6 +27,15 @@ serde_json = "1.0.145"
 unicode-segmentation = "1.12.0"
 simd-json = { version = "0.17", features = ["serde_impl"] }
 content_inspector = "0.2"
+yaml-rust2 = "0.10"
+
+ 
+
+[features]
+default = []
+
+[lib]
+doctest = false
 
 [dev-dependencies]
 insta = "1.40.0"
@@ -35,6 +44,7 @@ test_each_file = "0.3"
 rand = "0.9"
 rand_chacha = "0.9"
 tempfile = "3"
+serde_yaml = "0.9"
 
 [profile.release]
 # Prioritize runtime speed for large inputs

{headson-0.6.1 → headson-0.6.3}/PKG-INFO

@@ -1,13 +1,12 @@
 Metadata-Version: 2.4
 Name: headson
-Version: 0.6.1
+Version: 0.6.3
 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
@@ -21,7 +20,7 @@ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
   <br/>
 </p>
 
-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.
+`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.)
 
 Available as:
 - CLI (see [Usage](#usage))
@@ -41,11 +40,15 @@ From source:
 
 ## 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*
+- Budgeted output: specify exactly how much you want to see
+- Output formats: `auto | json | yaml | text`
+  - Styles: `strict | default | detailed`
+    - JSON family: `strict` → strict JSON, `default` → human‑friendly Pseudo, `detailed` → JS with inline comments
+    - YAML: always YAML; `strict` has no comments, `default` uses “# …”, `detailed` uses “# N more …”
+    - Text: prints raw lines. In `default` style, omissions are shown as a single line `…`; in `detailed`, as `… N more lines …`. `strict` omits array‑level summaries.
+- Multiple inputs: preview many files at once with a shared or per‑file budget
+- Fast: processes gigabyte‑scale files in seconds (mostly disk‑bound)
+- Available as a CLI app and as a Python library
 
 ## Fits into command line workflows
 
@@ -59,47 +62,74 @@ If you’re comfortable with tools like `head` and `tail`, use `headson` when yo
 
     headson [FLAGS] [INPUT...]
 
-- INPUT (optional, repeatable): file path(s). If omitted, reads JSON from stdin. Multiple input files are supported.
+- INPUT (optional, repeatable): file path(s). If omitted, reads 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 default 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).
-  - When used together with `--budget`, the final total budget is `min(global, per_file * number_of_inputs)`. Files are only truncated if they don't fit into this final global limit, and no single file expands beyond the per‑file budget.
-- `-f, --template <json|pseudo|js>`: output style (default: `pseudo`)
+- `-n, --budget <BYTES>`: per‑file output budget. For multiple inputs, default total budget is `<BYTES> * number_of_inputs`.
+- `-N, --global-budget <BYTES>`: total output budget across all inputs. With `--budget`, the effective total is the smaller of the two.
+- `-f, --format <auto|json|yaml|text>`: output format (default: `auto`).
+  - Auto: stdin → JSON family; filesets → per‑file based on extension (`.json` → JSON family, `.yaml`/`.yml` → YAML, unknown → Text).
+- `-t, --template <strict|default|detailed>`: output style (default: `default`).
+  - JSON family: `strict` → strict JSON; `default` → Pseudo; `detailed` → JS with inline comments.
+  - YAML: always YAML; style only affects comments (`strict` none, `default` “# …”, `detailed` “# N more …”).
+- `-i, --input-format <json|yaml|text>`: ingestion format (default: `json`). For filesets in `auto` format, ingestion is chosen by extensions.
 - `-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)
-- `--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`.
+- `--head`: prefer the beginning of arrays when truncating (keep first N). Strings are unaffected. Display styles place omission markers accordingly; strict JSON remains unannotated. Mutually exclusive with `--tail`.
+- `--tail`: prefer the end of arrays when truncating (keep last N). Strings are unaffected. Display styles place omission markers accordingly; strict JSON remains unannotated. Mutually exclusive with `--head`.
 
 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.
-  - 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.
+- Multiple inputs:
+  - With newlines enabled, file sections are rendered with human‑readable headers. In compact/single‑line modes, headers are omitted.
+- In `--format auto`, each file uses its own best format: JSON family for `.json`, YAML for `.yaml`/`.yml`.
+  - Unknown extensions are treated as Text (raw lines) — safe for logs and `.txt` files.
+  - `--global-budget` may truncate or omit entire files to respect the total budget.
+  - The tool finds the largest preview that fits the budget; even if extremely tight, you still get a minimal, valid preview.
+  - Directories and binary files are ignored; a notice is printed to stderr for each. Stdin reads the stream as‑is.
+  - Head vs Tail sampling: these options bias which part of arrays are kept before rendering. Display styles may still insert internal gap markers to honor very small budgets; strict JSON stays unannotated.
 
 Quick one‑liners:
 
 - Peek a big JSON stream (keeps structure):
 
-      zstdcat huge.json.zst | headson -n 800 -f pseudo
+      zstdcat huge.json.zst | headson -n 800 -f json -t default
 
 - Many files with a fixed overall size:
 
-      headson -N 1200 -f json logs/*.json
+      headson -N 1200 -f json -t strict logs/*.json
 
 - Glance at a file, JavaScript‑style comments for omissions:
 
-      headson -n 400 -f js data.json
+      headson -n 400 -f json -t detailed data.json
+
+- YAML with detailed comments:
+
+      headson -n 400 -f yaml -t detailed config.yaml
+
+### Text mode
+
+- Single file (auto):
+
+      headson -n 200 notes.txt
+
+- Force Text ingest/output (useful when mixing with other extensions):
+
+      headson -n 200 -i text -f text notes.txt
+
+- Many text files (fileset):
+
+      headson -n 800 -i text -f text logs/*.txt
+
+- Styles on Text:
+  - default: omission as a standalone `…` line.
+  - detailed: omission as `… N more lines …`.
+  - strict: no array‑level omission line (individual long lines may still truncate with `…`).
 
 Show help:
 
@@ -120,10 +150,10 @@ 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):
+Structured preview with headson (JSON family, default style → Pseudo):
 
 ```bash
-headson -n 120 -f pseudo users.json
+headson -n 120 -f json -t default users.json
 # {
 #   users: [
 #     { id: 1, name: "Ana", roles: [ "admin", … ] },
@@ -133,10 +163,10 @@ headson -n 120 -f pseudo users.json
 # }
 ```
 
-Machine‑readable preview (json):
+Machine‑readable preview (JSON family, strict style → strict JSON):
 
 ```bash
-headson -n 120 -f json users.json
+headson -n 120 -f json -t strict users.json
 # {"users":[{"id":1,"name":"Ana","roles":["admin"]}],"meta":{"count":2}}
 ```
 
@@ -148,36 +178,44 @@ Regenerate locally:
 - Run: cargo make tapes
 - Outputs are written to docs/assets/tapes
 
+
 ## 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).
+- 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, skew: str = "balanced") -> str`
-    - `template`: one of `"json" | "pseudo" | "js"`
+  - `headson.summarize(text: str, *, format: str = "auto", style: str = "default", input_format: str = "json", character_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)
-    - `skew`: one of `"balanced" | "head" | "tail"` (focus arrays on start vs end; only affects display templates; `json` remains strict).
+    - `skew`: `"balanced" | "head" | "tail"` (affects display styles; strict JSON remains unannotated)
 
-Example:
+Examples:
 
 ```python
 import json
 import headson
 
 data = {"foo": [1, 2, 3], "bar": {"x": "y"}}
-preview = headson.summarize(json.dumps(data), template="json", character_budget=200)
+preview = headson.summarize(json.dumps(data), format="json", style="strict", character_budget=200)
 print(preview)
 
-# Prefer the tail of arrays (annotations show in pseudo/js only)
+# Prefer the tail of arrays (annotations show with style="default"/"detailed")
 print(
     headson.summarize(
         json.dumps(list(range(100))),
-        template="pseudo",
+        format="json",
+        style="detailed",
         character_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))
 ```
 
 # Algorithm