headson 0.6.1__cp310-abi3-win_amd64.whl → 0.6.3__cp310-abi3-win_amd64.whl

headson/__init__.py

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

{headson-0.6.1.dist-info → headson-0.6.3.dist-info}/METADATA

@@ -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

headson-0.6.3.dist-info/RECORD

@@ -0,0 +1,5 @@
+headson-0.6.3.dist-info/METADATA,sha256=1KJILJz19mAFsItaIP8HJGiyDyUZyOGqQSQEQxcjRoE,10720
+headson-0.6.3.dist-info/WHEEL,sha256=4EDp_7DiFfWl1yYv5M4wSosAn5L_xgD1dyrQxQxfCx8,95
+headson/__init__.py,sha256=Z-vwzLN9ptomZrtRqVUuUKSAaidOSVcjFI6Ojbuj-dU,219
+headson/headson.pyd,sha256=9tzAWWQGEgz4Al25c_oAHG2cQIEv3sqBTyXXavPRnMk,773632
+headson-0.6.3.dist-info/RECORD,,

headson-0.6.1.dist-info/RECORD

@@ -1,6 +0,0 @@
-headson-0.6.1.dist-info/METADATA,sha256=K9PGA8lKK8Z8DS36LgA-mNreoL7x_gQ1mnjgatV3Z4E,9188
-headson-0.6.1.dist-info/WHEEL,sha256=4EDp_7DiFfWl1yYv5M4wSosAn5L_xgD1dyrQxQxfCx8,95
-headson-0.6.1.dist-info/licenses/LICENSE,sha256=85XxIce4vPe2JysuORWOYpzGI-ypir_79W6aOF8y534,1093
-headson/__init__.py,sha256=8DXFB8ahlywyQXJsscl3w_wgbcQi7sj7zEuV28wR60E,187
-headson/headson.pyd,sha256=zFa5yaOO1Ehn44y61G7i6pJSCvvS3q08b9VGKTYoruk,459776
-headson-0.6.1.dist-info/RECORD,,

headson-0.6.1.dist-info/licenses/LICENSE

@@ -1,21 +0,0 @@
-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.