agent-first-data 0.21.0

A naming convention that lets AI agents understand your data without being told what it means, plus a CLI and library for reading and safely editing structured JSON, TOML, YAML, dotenv, and INI documents.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

"""Policy test: runtime sources must not write to stderr outside the emitter's sink.

The spec's CLI Event Framing sanctions one path to stderr — the emitter's own
formatted diagnostic sink (``CliEmitter.finite`` / ``CliEmitter.from_output_to``
hand ``sys.stderr`` to the emitter, which routes ``error``/``progress``/``log``
through it). Merely referencing ``sys.stderr`` to pass it as that sink is allowed.
What stays forbidden is *ad-hoc* stderr writes that bypass the formatter:
``sys.stderr.write(...)`` / ``.writelines(...)`` and ``print(..., file=sys.stderr)``.
"""

from pathlib import Path
import re


# Forbid ad-hoc stderr writes that bypass the emitter's formatted sink. A bare
# `sys.stderr` reference (handing the stream to CliEmitter as its diagnostic
# sink) is the sanctioned exception and intentionally not matched here.
DISALLOWED = re.compile(
    r"\bfile\s*=\s*sys\.stderr\b"          # print(..., file=sys.stderr)
    r"|\bstderr\.(?:write|writelines)\s*\(",  # sys.stderr.write(...) / .writelines(...)
)


def test_no_ad_hoc_stderr_writes_in_runtime_sources() -> None:
    root = Path(__file__).resolve().parents[1] / "agent_first_data"
    files = sorted(root.glob("*.py"))
    assert files, "no python source files found"

    violations: list[str] = []
    for path in files:
        if path.name == "stream_redirect.py":
            continue
        for lineno, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
            if DISALLOWED.search(line):
                violations.append(f"{path.name}:{lineno}: {line.strip()}")

    assert not violations, "ad-hoc stderr writes are disallowed:\n" + "\n".join(violations)


def test_policy_permits_emitter_sink_but_forbids_ad_hoc_writes() -> None:
    # Sanctioned: handing sys.stderr to the emitter as its diagnostic sink.
    assert not DISALLOWED.search("return cls.finite_with(sys.stdout, sys.stderr, format)")
    assert not DISALLOWED.search("return cls.stream(sys.stderr, format, output_options, log_fields)")
    assert not DISALLOWED.search("CliEmitter.from_output_to(OutputTo.SPLIT, fmt)")
    # Forbidden: ad-hoc stderr writes that bypass the emitter.
    assert DISALLOWED.search("sys.stderr.write('boom')")
    assert DISALLOWED.search("sys.stderr.writelines(lines)")
    assert DISALLOWED.search("print('boom', file=sys.stderr)")