fux-decoder-config 4.1.1__py3-none-any.whl

fux_decoder_config/__init__.py

@@ -0,0 +1,12 @@
+"""`fux_decoder_config` — the fux-decoder-config package (W-289, SR-PLUGINS).
+
+One fux decoder module per format it reads: `fux_decoder_config.toml`, `fux_decoder_config.yaml`, `fux_decoder_config.ini`. Each is the
+decoder protocol of SR-DECODE — `EXTENSIONS`, `VERSION`, `USES` and
+`decode(raw, rel_path)` — moved here unchanged from `src/fux/decode/` in
+W-289 phase 2.
+
+**fux loads a module from here only when `.fux/plugins.toml` declares this
+package**, after verifying its version and digest (SR-PLUGINS P3, P4), by its
+fixed import name (P7). A same-named file in `.fux/decoders/` overrides it
+(P8). This file runs nothing: importing the package imports no decoder.
+"""

fux_decoder_config/ini.py

@@ -0,0 +1,67 @@
+"""INI and Java `.properties` -> Markdown.
+
+`configparser` is stdlib and handles INI. `.properties` is close but not the
+same — `key=value` with no sections at all — so it is normalised into a single
+implicit section rather than given its own module: they are one format with two
+spellings, and splitting them would give a consumer two things to override to
+change one behaviour.
+"""
+
+from __future__ import annotations
+
+import configparser
+
+# Imports are ABSOLUTE, not relative, and that is what makes this file work in
+# both places it runs: as a package module, and as a consumer copy in
+# `.fux/decoders/` loaded by path. A path-loaded file has no parent package, so
+# `from . import _xml` raises `attempted relative import with no known parent
+# package` — the copy would be dead on arrival. Absolute imports mean the file
+# fux ships and the file you edit are byte-identical (SR-DECODE decision 11).
+from fux_decoder_json.json import _prose
+from fux.constants import fixed
+
+#: **The reuse key's handle on this decoder** (W-166). Bump it by hand in the
+#: same change as any edit that can change what `decode()` returns, and the next
+#: `fux ingest` re-extracts the documents bound to THIS decoder and no others.
+#: Leaving it alone is the claim that the edit cannot move a byte of output.
+#: `tests/decode/test_decoder_versions.py` fails on a changed module that did
+#: not bump it. [SR-DECODE](../../../../records/0139_decode.md) decision 11a.
+VERSION = fixed("decoders.ini", "version")  # not bumped by W-234: law handles in comments only; not bumped by W-288 (imports moved to decode/ext, same output; USES now carries the extensions' VERSIONs)
+
+EXTENSIONS = tuple(fixed("decoders.ini", "extensions"))
+#: The decoder extensions this decoder calls, read by the reuse key (SR-DECODE decision 24).
+USES = tuple(fixed("decoders.ini", "uses"))
+
+
+def decode(raw: bytes, rel_path: str) -> str | None:
+    text = raw.decode("utf-8-sig", errors="replace")
+    parser = configparser.ConfigParser(
+        # A `.properties` file is full of duplicate-looking keys and colons;
+        # strict mode would reject the file entirely over one repeat, which
+        # turns a readable document into a skipped one for no gain.
+        strict=False,
+        interpolation=None,  # `%(x)s` in a value is text here, not a template
+        delimiters=("=", ":"),
+        allow_no_value=True,
+    )
+    try:
+        parser.read_string(text)
+    except (configparser.Error, UnicodeDecodeError):
+        # `.properties` has no section header at all, which configparser
+        # rejects. Give it the implicit one the format assumes.
+        try:
+            parser.read_string("[properties]\n" + text)
+        except configparser.Error:
+            return None
+
+    blocks: list[str] = []
+    # `parser.sections()` is document order; sorting makes two files that
+    # differ only in section order decode identically (L4).
+    for section in sorted(parser.sections()):
+        blocks.append("## " + section)
+        for key in sorted(parser[section]):
+            value = parser[section][key]
+            text_value = _prose(value) if value is not None else ""
+            blocks.append(f"**{key}:** {text_value}" if text_value else f"**{key}**")
+    body = "\n\n".join(blocks)
+    return body if body.strip() else None

fux_decoder_config/toml.py

@@ -0,0 +1,71 @@
+"""TOML -> Markdown. Free: `tomllib` is stdlib on the Python L7 already requires.
+
+Same shape as `json` and for the same reason — a table name is a heading, a
+string value is prose, a number is not a word. It is a separate module rather
+than a branch inside `json` because the override seam works **by module
+name**: a consumer who wants different TOML handling must be able to take that
+and nothing else.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from fux.decode.ext.limits import limit
+
+# Imports are ABSOLUTE, not relative, and that is what makes this file work in
+# both places it runs: as a package module, and as a consumer copy in
+# `.fux/decoders/` loaded by path. A path-loaded file has no parent package, so
+# `from . import _xml` raises `attempted relative import with no known parent
+# package` — the copy would be dead on arrival. Absolute imports mean the file
+# fux ships and the file you edit are byte-identical (SR-DECODE decision 11).
+from fux_decoder_json.json import _prose
+from fux.constants import fixed
+
+#: Markdown has six heading levels; a deeper one is clamped, never invented.
+_MAX_HEADING = fixed("markdown", "max_heading")
+
+#: **The reuse key's handle on this decoder** (W-166). Bump it by hand in the
+#: same change as any edit that can change what `decode()` returns, and the next
+#: `fux ingest` re-extracts the documents bound to THIS decoder and no others.
+#: Leaving it alone is the claim that the edit cannot move a byte of output.
+#: `tests/decode/test_decoder_versions.py` fails on a changed module that did
+#: not bump it. [SR-DECODE](../../../../records/0139_decode.md) decision 11a.
+VERSION = fixed("decoders.toml", "version")  # not bumped by W-225 4a (caps moved, same values) nor 5b (numerals moved, same output); not bumped by W-288 (imports moved to decode/ext, same output; USES now carries the extensions' VERSIONs)
+
+EXTENSIONS = tuple(fixed("decoders.toml", "extensions"))
+#: The decoder extensions this decoder calls, read by the reuse key (SR-DECODE decision 24).
+USES = tuple(fixed("decoders.toml", "uses"))
+
+
+def decode(raw: bytes, rel_path: str) -> str | None:
+    try:
+        data = tomllib.loads(raw.decode("utf-8-sig"))
+    except (UnicodeDecodeError, tomllib.TOMLDecodeError):
+        return None
+    lines: list[str] = []
+    _walk(data, lines, depth=1, label=None)
+    body = "\n\n".join(lines)
+    return body if body.strip() else None
+
+
+def _walk(node, out: list[str], *, depth: int, label: str | None) -> None:
+    if depth > limit("json", "max_depth"):
+        return
+    if isinstance(node, dict):
+        if label:
+            out.append("#" * min(depth, _MAX_HEADING) + " " + label)
+        for key in sorted(node, key=str):
+            _walk(node[key], out, depth=depth + 1, label=str(key))
+        return
+    if isinstance(node, list):
+        if label:
+            out.append("#" * min(depth, _MAX_HEADING) + " " + label)
+        for item in node:
+            _walk(item, out, depth=depth + 1, label=None)
+        return
+    # `tomllib` returns real `datetime` objects for dates, so unlike JSON the
+    # timestamp noise never reaches `_prose` as a string — it is dropped here
+    # by not being a `str` at all.
+    text = _prose(node)
+    if text:
+        out.append(f"**{label}:** {text}" if label else text)

fux_decoder_config/yaml.py

@@ -0,0 +1,164 @@
+"""YAML -> Markdown. **A deliberate subset, and the subset is the correct
+option rather than the cheap one.**
+
+The extra 80 % of the YAML 1.2 spec is **type resolution** — is `NO` the string
+"NO" or the boolean false, is `1:30` a sexagesimal, is `2024-01-01` a date.
+Fux consumes **words**, not types, so none of that changes a single term while
+all of it is L2 surface owned forever.
+
+Worse, one full-spec behaviour is **actively wrong here**:
+
+* **Anchors and aliases (`&a` / `*a`).** A conformant parser expands an alias
+  everywhere it appears, which **duplicates the anchored text and inflates
+  `tf`** — a document mentioning a term once would rank as though it mentioned
+  it five times. This module reads the anchor's text once and never expands.
+* **Nested aliases** are the billion-laughs bomb in YAML clothing: exponential
+  expansion, unbounded memory, from a file sitting in a git repo.
+
+So a "full YAML parser" for fux would be a conformant parser that then
+deliberately violates the spec at the one place that matters. The subset is
+what is left when you keep only what carries text: indentation, `key:`,
+`- ` items, quoting, block scalars `|` and `>`, and multi-document `---`.
+
+⚠ **`frontmatter.py` is fux's other hand-rolled YAML subset.** Two dialects in
+one codebase is the `_MdParser` defect again, so
+`tests/decode/test_decode.py` asserts the two agree on the shapes both accept.
+"""
+
+from __future__ import annotations
+
+import re
+from fux.decode.ext.limits import limit
+
+# Imports are ABSOLUTE, not relative, and that is what makes this file work in
+# both places it runs: as a package module, and as a consumer copy in
+# `.fux/decoders/` loaded by path. A path-loaded file has no parent package, so
+# `from . import _xml` raises `attempted relative import with no known parent
+# package` — the copy would be dead on arrival. Absolute imports mean the file
+# fux ships and the file you edit are byte-identical (SR-DECODE decision 11).
+from fux_decoder_json.json import _label, _prose
+from fux.constants import fixed
+
+#: **The reuse key's handle on this decoder** (W-166). Bump it by hand in the
+#: same change as any edit that can change what `decode()` returns, and the next
+#: `fux ingest` re-extracts the documents bound to THIS decoder and no others.
+#: Leaving it alone is the claim that the edit cannot move a byte of output.
+#: `tests/decode/test_decoder_versions.py` fails on a changed module that did
+#: not bump it. [SR-DECODE](../../../../records/0139_decode.md) decision 11a.
+VERSION = fixed("decoders.yaml", "version")  # not bumped by W-234: law handles in comments only; W-225 4a (caps moved, same values) nor 5b (numerals moved, same output); not bumped by W-288 (imports moved to decode/ext, same output; USES now carries the extensions' VERSIONs)
+
+EXTENSIONS = tuple(fixed("decoders.yaml", "extensions"))
+#: The decoder extensions this decoder calls, read by the reuse key (SR-DECODE decision 24).
+USES = tuple(fixed("decoders.yaml", "uses"))
+
+#: ⚠ **`MAX_DEPTH` is `[limits.yaml] max_depth` in .fux/formats.toml** since W-225 stage 4a
+#: (SR-LAW-12 decision 9b): read per call through `limit()`, in the extract-config digest.
+
+#: `key:` or `key: value`, capturing indentation. Anchors and tags are stripped
+#: from the value rather than interpreted — `&id001`, `*id001`, `!!str` are
+#: type/graph machinery, and none of them is a word.
+_KEY_RE = re.compile(r"^(?P<indent>\s*)(?P<key>[^\s#][^:]*?)\s*:\s*(?P<value>.*)$")
+_ITEM_RE = re.compile(r"^(?P<indent>\s*)-\s*(?P<value>.*)$")
+_NOISE_PREFIX = re.compile(r"^(?:[&*][^\s]+|![^\s]*)\s*")
+_BLOCK_SCALAR = re.compile(r"^[|>][-+]?\d*$")
+
+
+def decode(raw: bytes, rel_path: str) -> str | None:
+    text = raw.decode("utf-8-sig", errors="replace")
+    out: list[str] = []
+    block_indent: int | None = None
+    block_lines: list[str] = []
+    block_lines_indent: list[int | None] = [None]
+
+    for line in text.splitlines():
+        if block_indent is not None:
+            # Inside a block scalar: content is literal text until the
+            # indentation drops back. This is the one place YAML carries real
+            # prose in bulk — a description, a script, a runbook step.
+            if not line.strip() or _indent(line) > block_indent:
+                # Dedent by the block's OWN first-line indentation, not by the
+                # key's + 1. YAML lets a block be indented any amount past its
+                # key, so a fixed guess leaves a ragged leading space on every
+                # line — invisible in a diff and present in every term's context.
+                if block_lines_indent[0] is None and line.strip():
+                    block_lines_indent[0] = _indent(line)
+                strip = block_lines_indent[0] or 0
+                block_lines.append(line[strip:] if line.strip() else "")
+                continue
+            _flush_block(block_lines, out)
+            block_indent, block_lines = None, []
+            block_lines_indent[0] = None
+
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if stripped in ("---", "..."):
+            continue  # a document boundary; every document in the file is indexed
+
+        item = _ITEM_RE.match(line)
+        if item and not _KEY_RE.match(item.group("value")):
+            value = _clean(item.group("value"))
+            if value:
+                out.append("- " + value)
+            continue
+
+        match = _KEY_RE.match(line)
+        if not match:
+            value = _clean(stripped)
+            if value:
+                out.append(value)
+            continue
+
+        key = _clean(match.group("key")).strip("\"'")
+        value = match.group("value").strip()
+        if _BLOCK_SCALAR.match(value):
+            if key:
+                out.append(f"**{key}:**")
+            block_indent = _indent(line)
+            block_lines = []
+            block_lines_indent[0] = None
+            continue
+        value = _clean(value)
+        depth = _indent(line) // limit("yaml", "indent_step") + 1
+        if not value:
+            if key:
+                out.append(_label(key, min(depth, limit("yaml", "max_depth"))))
+        else:
+            prose = _prose(value) or value if len(value) >= limit("yaml", "min_value_len") else ""
+            if prose:
+                out.append(f"**{key}:** {prose}")
+
+    if block_indent is not None:
+        _flush_block(block_lines, out)
+
+    body = "\n\n".join(o for o in out if o.strip())
+    return body if body.strip() else None
+
+
+def _flush_block(lines: list[str], out: list[str]) -> None:
+    text = "\n".join(lines).strip("\n")
+    if text.strip():
+        out.append(text)
+
+
+def _indent(line: str) -> int:
+    return len(line) - len(line.lstrip())
+
+
+def _clean(value: str) -> str:
+    """Strip anchors, aliases, tags, quotes and trailing comments.
+
+    An alias is dropped rather than resolved — see the module docstring. This
+    is the single most consequential line in the file: resolving it would
+    inflate `tf` and quietly change every ranking over a YAML corpus.
+    """
+    value = _NOISE_PREFIX.sub("", value.strip())
+    if value.startswith(("'", '"')) and len(value) > 1:
+        quote = value[0]
+        end = value.rfind(quote)
+        if end > 0:
+            return value[1:end]
+    hash_at = value.find(" #")
+    if hash_at >= 0:
+        value = value[:hash_at]
+    return value.strip()

fux_decoder_config-4.1.1.dist-info/METADATA

@@ -0,0 +1,31 @@
+Metadata-Version: 2.5
+Name: fux-decoder-config
+Version: 4.1.1
+Summary: Fux decoder package: configuration files — TOML, YAML, INI.
+Project-URL: Homepage, https://github.com/arpitarya/fux
+Project-URL: Repository, https://github.com/arpitarya/fux
+Author-email: arpit arya <arpitarya.me@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: fux-core==4.1.1
+Requires-Dist: fux-decoder-json==4.1.1
+Description-Content-Type: text/markdown
+
+# fux-decoder-config
+
+Part of [fux](https://github.com/arpitarya/fux) — rank your written knowledge
+from a small index committed to git; fetch content from the systems that own
+it; verify freshness at answer time.
+
+**`fux-decoder-config` is a fux decoder package: configuration files — TOML, YAML, INI.** Only `fux-engine` is mandatory;
+everything else is declared per repository in the committed
+`.fux/plugins.toml`, pinned to one version and digest, and refused loudly when
+it is missing or differs, so two machines on one repository never build
+different indexes.
+
+It reads `.toml` `.yaml` `.yml` `.ini` `.cfg` `.properties`. Install it and declare it in `.fux/plugins.toml` --
+`fux setup` proposes it when your sources hold those files -- or fux does not
+read them, and `fux doctor` says so.
+
+It is released on fux's own version, together with every other fux package.
+Documentation: <https://github.com/arpitarya/fux#readme>

fux_decoder_config-4.1.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+fux_decoder_config/__init__.py,sha256=d5bkwLFQAYfM2332fRkkKg9wlsLIrBqkQkpjnxfOm18,682
+fux_decoder_config/ini.py,sha256=NLgU0snwXHql8lKjioLbdPPBUmH9COZfNKuyFxJJwjw,3309
+fux_decoder_config/toml.py,sha256=muFtUY2t-uH-Gc4EciiLeo5ykGRoEwttNKtf7dz8qhA,3302
+fux_decoder_config/yaml.py,sha256=uuh2mmxWmIXb_zTdM-fvIdRccjO-VU8Gpw4E2PVN_v4,7392
+fux_decoder_config-4.1.1.dist-info/METADATA,sha256=WcnYMdjXqsitkCsOs9by5GleLKF9z_u7KUWX9F9FeH8,1390
+fux_decoder_config-4.1.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fux_decoder_config-4.1.1.dist-info/RECORD,,

fux_decoder_config-4.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any