knf-cli 0.2.0__py3-none-win_amd64.whl

knf_cli-0.2.0.dist-info/METADATA

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: knf-cli
+Version: 0.2.0
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Utilities
+License-File: LICENSE
+Summary: Merge layered configuration files and print the result
+Keywords: configuration,json,toml,cli
+License-Expression: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Issues, https://github.com/binado/knf/issues
+Project-URL: Repository, https://github.com/binado/knf
+
+# knf
+
+Merges layered configuration files and prints the result. One job, no query
+language, no template engine.
+
+```bash
+# Print the output to stdout
+knf base.toml prod.toml > merged.toml
+# Add manual overrides via the --set flag
+knf defaults.json overrides.json --set server.port=8080 --set host=name
+# Mix toml and json (if you want)
+knf *.toml *.json
+```
+
+It exists because more powerful alternatives (`yq ea '. as $i ireduce ({}; . * $i)'`,
+`jq -s 'reduce ...'`) require non-obvious incantations for what is a common,
+simple operation. `knf <files>` should need no explanation.
+
+## Installation
+
+```bash
+pip install knf-cli
+```
+
+The Python distribution is binary-only: it installs the `knf` executable and
+does not provide an importable Python module. Wheels are published for Linux
+(glibc and musl) on x86-64 and ARM64, macOS on Intel and Apple Silicon, and
+Windows on x64 and ARM64. No Rust toolchain is needed to install a wheel.
+
+To build from source instead:
+
+```bash
+cargo install knf-cli
+```
+
+## Rust libraries
+
+The whole pipeline — read paths, parse JSON and TOML, merge, interpolate — is
+`knf-config`, published separately from the command line so a Rust consumer or
+a language binding never pulls in `clap`:
+
+```bash
+cargo add knf-config
+```
+
+```rust
+use knf::{MergeOpts, merge};
+
+let merged = merge(&["base.toml", "prod.toml"], MergeOpts::default())?;
+```
+
+`MergeOpts` also accepts strict mode, per-path rules, in-memory terminal
+overlays, an input-format override, and opt-in interpolation. An overlay is a
+`knf::Map` rather than a value, for the reason a file layer must be an object at
+the top level: a scalar layer would replace the whole document instead of
+shadowing a key. The result is the format-independent `knf::Value`, ready for a
+native adapter or language binding to convert without parsing rendered stdout;
+`knf::format::emit` renders it when you do want text.
+
+With `interpolate` set, `merge` resolves `${env:NAME}` against the process
+environment; left unset, references are not substituted at all. Pass your own
+environment with `merge_with_env`, and the output is a function of the inputs
+alone:
+
+```rust
+let opts = MergeOpts { interpolate: true, ..MergeOpts::default() };
+let merged = knf::merge_with_env(&paths, opts, &my_env)?;
+```
+
+Errors carry typed causes rather than prose — `LoadError`, `MergeError`,
+`InterpError`, `TomlError` — and name no command-line flags, since a library
+caller has no command line to act on. A null reaching TOML, for instance, is
+reported as the paths it was found at; whether the remedy is spelled `-f json`
+is your interface's business, not the library's.
+
+`Map`, `Value`, `Rules`, `Strategy`, `Format`, `Env` and every error type are
+re-exported from `knf`, along with what they are made of — `Number` inside
+`Value::Number`, `Cycle` and `Syntax` inside `InterpError` — so a consumer needs
+no direct dependency on `knf-core` or `knf-interp` to write any of it down.
+
+For merging values that are already in memory, use the smaller core crate — it
+has no file I/O and no format crates, only `indexmap` and `thiserror`:
+
+```bash
+cargo add knf-core
+```
+
+```rust
+use knf_core::{Value, merge};
+
+let merged = merge([base, overlay])?;
+```
+
+## Merging
+
+Files are merged left to right in argument order. Exactly one document
+goes to stdout.
+
+| Case | Behaviour |
+| --- | --- |
+| object ⊕ object | recurse per key |
+| array ⊕ anything | **replace wholesale**, never index-merge or concat |
+| scalar ⊕ anything | last wins |
+| anything ⊕ null | null is an ordinary value; it overwrites |
+
+Two consequences worth knowing:
+
+- **Arrays replace**, unless `--append` names the path. Index-merging would turn
+  `["a"]` over `["x","y","z"]` into `["a","y","z"]` — a value nobody wrote.
+- **Null is a value, not a delete.** So `knf a.json` with one argument is always
+  a byte-level no-op.
+
+`--strict` errors when a layer changes the *type* of an existing key, which
+catches the class of mistake where a leaf accidentally shadows a subtree.
+
+```
+$ knf a.json b.json --strict
+error: type conflict at `server`: object would be replaced by number
+```
+
+### Override merge behavior on specific paths
+
+What if a document has one array that should be appended to, and not replaced? 
+`knf` understands how to override the merge behavior on a specifc path: 
+```bash
+knf base.toml prod.toml --append plugins    # concatenate, base ++ prod
+knf base.toml prod.toml --replace db        # take prod's [db] whole
+knf base.toml prod.toml --fail db.host      # error if prod overrides db.host
+```
+
+| Flag | At that path |
+| --- | --- |
+| `--append` | concatenate; both sides must be arrays |
+| `--replace` | assign wholesale, no recursion, even object over object |
+| `--fail` | error; the first layer to define the path pins it |
+
+### Variable and environment references
+
+A merged config often wants to refer to itself, or to the environment.
+`--interpolate` resolves `${key.path}` and `${env:VAR}` in string values, in one
+pass over the merged document:
+
+```toml
+# base.toml
+root     = "/srv"
+data_dir = "${root}/data"
+port     = "${env:PORT}"
+url      = "http://localhost:${env:PORT}/health"
+literal  = "$${NOT_A_REF}"
+```
+
+```console
+$ PORT=8080 knf base.toml --interpolate
+root = "/srv"
+data_dir = "/srv/data"
+port = 8080
+url = "http://localhost:8080/health"
+literal = "${NOT_A_REF}"
+```
+
+**It is opt-in, and off by default.** knf sits directly upstream of tools whose
+own syntax is `${...}` — compose files, GitHub Actions workflows, Helm charts,
+systemd units. Eating those without being asked would be silent corruption, so
+without the flag the output is byte for byte what it is today.
+
+Where the reference sits decides what it yields:
+
+| Position | Behaviour |
+| --- | --- |
+| whole string — `port = "${p}"` | takes the referent's **value and type**; `port` above is a number, and `"${db}"` is the whole table |
+| embedded — `url = "x/${p}"` | stringifies; an object or array has no format-independent spelling here, so it is an error |
+
+An environment variable is typed by the same rule as `--set`'s right-hand side
+when it is the whole string, and spliced as raw text when it is embedded —
+parsing it only to print it again could only lose something.
+
+`$$` is a literal `$`. A `$` followed by anything else is ordinary text, so
+`USD $5` needs no escaping.
+
+Document references resolve transitively and in any order; environment values
+are terminal and are never re-scanned. Cycles are an error, and so is a
+reference that names nothing:
+
+```
+$ knf base.toml --interpolate
+error: unresolved reference
+  --> server.url: `db.hostname`
+  --> tags[0]: `env:REGION`
+help: `${key.path}` names a key in the merged document, `${env:NAME}` an environment variable
+help: drop --interpolate to pass `${...}` through untouched
+```
+
+A reference may also read an array element — `${servers[0].host}` — with the
+same two-position rules: whole-string it takes the element's value and type,
+embedded it stringifies.
+
+Two limits worth knowing:
+
+- **`env:` is a reserved prefix**, matched literally rather than by splitting on
+  the first `:`. So `${a:b}` is the ordinary key `a:b`, and only keys that
+  literally begin `env:` are unaddressable.
+- **A key spelled with brackets is unaddressable** — `${a[0]}` now reads as *the
+  first element of `a`*, never as a key literally named `a[0]`, and
+  `--set 'a[0]=1'` is an error rather than a write into an array. Only a file
+  can carry such a key. The same accepted loss as keys containing a literal
+  dot, which the dotted grammars have always excluded.
+
+`--set` layers interpolate like any other layer. `--strict` runs during the
+merge, before any substitution, so it compares the types values had when they
+were written.
+
+## Caveats with formats
+
+JSON and TOML, inferred from the file extension. `--input-format` overrides it
+for every input and is required for `-` (stdin).
+
+Output is the inputs' format when they agree; when they don't, `-f` is required
+rather than guessed, so reordering arguments can never silently change the
+encoding. Pretty-printed by default; `--compact` opts out.
+
+A TOML datetime is a distinct type all the way through the merge, so every TOML
+output keeps it unquoted — including a merge that mixed in a JSON layer, and
+including `--set` on top. It becomes a plain string only under `-f json`, where
+there is nothing else it could be.
+
+TOML cannot represent null, so emitting TOML from a document containing one is
+an error that names every path:
+
+```
+$ knf base.toml override.json -f toml
+error: cannot serialize null to TOML
+  --> servers.primary.proxy
+  --> logging.sink
+help: emit JSON with -f json, substitute with --null-as, or remove the null
+```
+
+Alternatively, you may use `--null-as <string>` to parse nulls into a custom value:
+
+```bash
+knf base.toml override.json -f toml --null-as=none
+```
+The option is a no-op for JSON output. 
+
+Two more values have no spelling in one format or the other, and both are
+rejected the same way — named by path, never silently substituted.
+
+TOML integers are signed 64-bit, so an ID above `i64::MAX` (a snowflake, a hash)
+round-trips exactly through JSON but cannot be written as TOML at all:
+
+```
+$ knf ids.json -f toml
+error: cannot serialize integer to TOML
+  --> id: `10000000000000000001`
+help: TOML integers are signed 64-bit; emit JSON with -f json
+```
+
+Conversely, TOML's number grammar has `inf`, `-inf` and `nan` literals and
+JSON's has none of them:
+
+```
+$ knf limits.toml -f json
+error: cannot serialize non-finite number to JSON
+  --> timeout: `inf`
+help: emit TOML with -f toml, which can represent inf and nan
+```
+
+Each format is the escape from the other's rejection, and no same-format
+round-trip is affected: `knf ids.json -f json` and `knf limits.toml -f toml`
+both emit their input unchanged.
+
+## Testing
+
+```bash
+cargo test --workspace
+cargo test -p knf-core           # fast inner loop: no filesystem, no process
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+

knf_cli-0.2.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+knf_cli-0.2.0.data/scripts/knf.exe,sha256=XgTlvjNwW6fT93tG2vO_HwPSzUU0EX4bV6RIywMQjxE,1401344
+knf_cli-0.2.0.dist-info/METADATA,sha256=XGIC-2-_BxO1LX9kGsZMgxvMIS4zFcj6DiT_DZkvuXA,10820
+knf_cli-0.2.0.dist-info/WHEEL,sha256=2zDlIYIdD4m4N3p5DVEG3iJhGLdhsBQgdH-FqVkAur8,94
+knf_cli-0.2.0.dist-info/licenses/LICENSE,sha256=TSgg6ifXVXaxLfM0VK34j3fsXohLrTcsrxNmJHVb2EQ,1101
+knf_cli-0.2.0.dist-info/sboms/knf-cli.cyclonedx.json,sha256=qvONzCt_RDETNPF_ezXUUaFGm8U6skgi9JeEjEw_kuc,43501
+knf_cli-0.2.0.dist-info/RECORD,,

knf_cli-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.14.1)
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64

knf_cli-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bernardo Porto Veronese
+
+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.