agent-first-data 0.13.0__tar.gz → 0.13.2__tar.gz

{agent_first_data-0.13.0 → agent_first_data-0.13.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.13.0
+Version: 0.13.2
 Summary: A naming convention that lets AI agents understand your data without being told what it means.
 License-Expression: MIT
 Project-URL: Repository, https://github.com/agentfirstkit/agent-first-data
@@ -29,7 +29,7 @@ print(output_json(value))
 print(output_plain(value))
 ```
 
-Useful names use Python casing: `output_json`, `output_yaml`, `output_plain`, `output_json_with_options`, `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `parse_size`, `normalize_utc_offset`, `cli_parse_output`, `cli_output`, and `build_cli_error`.
+Useful names use Python casing: `output_json`, `output_yaml`, `output_plain`, `output_json_with_options`, `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `parse_size`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `cli_parse_output`, `cli_output`, `build_cli_error`, `build_cli_version`, and `cli_handle_version_or_continue`.
 
 Logging is available through `init_logging_json`, `init_logging_plain`, `init_logging_yaml`, `span`, and `get_logger`.
 
@@ -46,6 +46,7 @@ init_logging_json("INFO", secret_names=("authorization",))
 - YAML/plain quote and escape keys as well as values, sort by UTF-16 code unit order, and render nested objects in arrays as canonical JSON.
 - Logging records use `code: "log"` plus a separate `level` field, so error-level logs are not terminal protocol errors.
 - `build_cli_error(message, hint?)` returns `{code:"error", error: message, hint?}` only.
+- Use `cli_handle_version_or_continue()` before argument parsing so bare `--version` stays conventional and `--version --output json|yaml|plain` stays structured.
 
 ## Reference
 

{agent_first_data-0.13.0 → agent_first_data-0.13.2}/README.md

@@ -20,7 +20,7 @@ print(output_json(value))
 print(output_plain(value))
 ```
 
-Useful names use Python casing: `output_json`, `output_yaml`, `output_plain`, `output_json_with_options`, `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `parse_size`, `normalize_utc_offset`, `cli_parse_output`, `cli_output`, and `build_cli_error`.
+Useful names use Python casing: `output_json`, `output_yaml`, `output_plain`, `output_json_with_options`, `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `parse_size`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `cli_parse_output`, `cli_output`, `build_cli_error`, `build_cli_version`, and `cli_handle_version_or_continue`.
 
 Logging is available through `init_logging_json`, `init_logging_plain`, `init_logging_yaml`, `span`, and `get_logger`.
 
@@ -37,6 +37,7 @@ init_logging_json("INFO", secret_names=("authorization",))
 - YAML/plain quote and escape keys as well as values, sort by UTF-16 code unit order, and render nested objects in arrays as canonical JSON.
 - Logging records use `code: "log"` plus a separate `level` field, so error-level logs are not terminal protocol errors.
 - `build_cli_error(message, hint?)` returns `{code:"error", error: message, hint?}` only.
+- Use `cli_handle_version_or_continue()` before argument parsing so bare `--version` stays conventional and `--version --output json|yaml|plain` stays structured.
 
 ## Reference
 

{agent_first_data-0.13.0 → agent_first_data-0.13.2}/agent_first_data/__init__.py

@@ -24,6 +24,8 @@ from agent_first_data.format import (
     redact_url_secrets_with_options,
     parse_size,
     normalize_utc_offset,
+    is_valid_rfc3339_date,
+    is_valid_rfc3339_time,
 )
 
 from agent_first_data.afdata_logging import (
@@ -42,6 +44,9 @@ from agent_first_data.cli import (
     cli_output,
     cli_output_with_options,
     build_cli_error,
+    build_cli_version,
+    cli_render_version,
+    cli_handle_version_or_continue,
 )
 
 from agent_first_data.skill import (
@@ -84,6 +89,8 @@ __all__ = [
     "redact_url_secrets_with_options",
     "parse_size",
     "normalize_utc_offset",
+    "is_valid_rfc3339_date",
+    "is_valid_rfc3339_time",
     "AfdataHandler",
     "init_logging_json",
     "init_logging_plain",
@@ -96,6 +103,9 @@ __all__ = [
     "cli_output",
     "cli_output_with_options",
     "build_cli_error",
+    "build_cli_version",
+    "cli_render_version",
+    "cli_handle_version_or_continue",
     "SkillSpec",
     "SkillAction",
     "SkillScope",

{agent_first_data-0.13.0 → agent_first_data-0.13.2}/agent_first_data/cli.py

@@ -7,6 +7,7 @@ from typing import Any
 
 from agent_first_data.format import (
     OutputOptions,
+    build_json,
     output_json,
     output_json_with_options,
     output_yaml,
@@ -93,6 +94,89 @@ def cli_output_with_options(
     return output_json_with_options(value, output_options)
 
 
+def build_cli_version(version: str) -> dict:
+    """Build a standard CLI version value."""
+    return build_json("version", {"version": version})
+
+
+def cli_render_version(
+    name: str,
+    version: str,
+    format: OutputFormat | None = None,
+) -> str:
+    """Render CLI version output.
+
+    Pass an OutputFormat for AFDATA JSON/YAML/plain. Pass None to preserve
+    conventional "<name> <version>" text.
+    """
+    rendered = (
+        f"{name} {version}" if format is None else cli_output(build_cli_version(version), format)
+    )
+    return rendered.rstrip("\n") + "\n"
+
+
+def cli_handle_version_or_continue(
+    raw_args: list[str],
+    name: str,
+    version: str,
+    default_output: OutputFormat | None = None,
+    output_flag: str = "--output",
+    allow_output_format: bool = True,
+) -> str | None:
+    """Render version output if --version/-V is present; otherwise return None.
+
+    Raises ValueError for malformed version requests, for example
+    ``--version --output xml``. The caller should convert that to a CLI error
+    with ``build_cli_error``.
+    """
+    version_requested = False
+    output_format: OutputFormat | None = None
+    output_error: ValueError | None = None
+
+    i = 0
+    while i < len(raw_args):
+        arg = raw_args[i]
+        if arg == "--":
+            break
+        if arg in ("--version", "-V"):
+            version_requested = True
+            i += 1
+            continue
+        if allow_output_format and (arg == output_flag or arg.startswith(f"{output_flag}=")):
+            value: str | None
+            if arg.startswith(f"{output_flag}="):
+                value = arg.split("=", 1)[1]
+                step = 1
+            elif i + 1 < len(raw_args) and not raw_args[i + 1].startswith("-"):
+                value = raw_args[i + 1]
+                step = 2
+            else:
+                value = None
+                step = 1
+            if value is None:
+                output_error = ValueError(
+                    f"missing value for {output_flag}: expected json, yaml, or plain"
+                )
+            else:
+                try:
+                    output_format = cli_parse_output(value)
+                except ValueError as e:
+                    output_error = e
+            i += step
+            continue
+        i += 1
+
+    if not version_requested:
+        return None
+    if output_error is not None:
+        raise output_error
+    return cli_render_version(
+        name,
+        version,
+        output_format if allow_output_format and output_format is not None else default_output,
+    )
+
+
 def build_cli_error(message: str, hint: str | None = None) -> dict:
     """Build a standard CLI parse error value.
 

{agent_first_data-0.13.0 → agent_first_data-0.13.2}/agent_first_data/format.py

@@ -1,10 +1,10 @@
 """AFDATA output formatting and protocol templates.
 
-19 public APIs and 4 types: protocol builders, value redactors (copy and
+21 public APIs and 4 types: protocol builders, value redactors (copy and
 in-place; cover _secret and _url fields), output formatters, URL-string
 redactors (redact_url_secrets / _with_options), parse_size,
-normalize_utc_offset, RedactionPolicy, RedactionOptions, OutputStyle, and
-OutputOptions.
+normalize_utc_offset, is_valid_rfc3339_date, is_valid_rfc3339_time,
+RedactionPolicy, RedactionOptions, OutputStyle, and OutputOptions.
 """
 
 from __future__ import annotations
@@ -293,6 +293,38 @@ def normalize_utc_offset(value: str) -> str | None:
     return f"{s[0]}{hours:02d}:{minutes:02d}"
 
 
+def is_valid_rfc3339_date(value: str) -> bool:
+    """Return true when value is an RFC 3339 full-date (YYYY-MM-DD)."""
+    if not isinstance(value, str):
+        return False
+    if len(value) != 10 or value[4] != "-" or value[7] != "-":
+        return False
+    year = _parse_ascii_int(value[0:4])
+    month = _parse_ascii_int(value[5:7])
+    day = _parse_ascii_int(value[8:10])
+    if year is None or month is None or day is None:
+        return False
+    return 1 <= month <= 12 and 1 <= day <= _days_in_month(year, month)
+
+
+def is_valid_rfc3339_time(value: str) -> bool:
+    """Return true when value is an RFC 3339 partial-time (HH:MM:SS[.fraction])."""
+    if not isinstance(value, str):
+        return False
+    if len(value) < 8 or value[2] != ":" or value[5] != ":":
+        return False
+    hour = _parse_ascii_int(value[0:2])
+    minute = _parse_ascii_int(value[3:5])
+    second = _parse_ascii_int(value[6:8])
+    if hour is None or minute is None or second is None:
+        return False
+    if hour > 23 or minute > 59 or second > 59:
+        return False
+    if len(value) == 8:
+        return True
+    return value[8] == "." and len(value) > 9 and value[9:].isdigit()
+
+
 def _parse_utc_offset_body(body: str) -> tuple[int, int] | None:
     if not body:
         return None
@@ -315,6 +347,26 @@ def _parse_utc_offset_body(body: str) -> tuple[int, int] | None:
     return None
 
 
+def _parse_ascii_int(value: str) -> int | None:
+    if not value or not (value.isascii() and value.isdigit()):
+        return None
+    return int(value)
+
+
+def _days_in_month(year: int, month: int) -> int:
+    if month in (1, 3, 5, 7, 8, 10, 12):
+        return 31
+    if month in (4, 6, 9, 11):
+        return 30
+    if month == 2:
+        return 29 if _is_leap_year(year) else 28
+    return 0
+
+
+def _is_leap_year(year: int) -> bool:
+    return year % 4 == 0 and (year % 100 != 0 or year % 400 == 0)
+
+
 # ═══════════════════════════════════════════
 # Secret Redaction
 # ═══════════════════════════════════════════

{agent_first_data-0.13.0 → agent_first_data-0.13.2}/agent_first_data.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.13.0
+Version: 0.13.2
 Summary: A naming convention that lets AI agents understand your data without being told what it means.
 License-Expression: MIT
 Project-URL: Repository, https://github.com/agentfirstkit/agent-first-data
@@ -29,7 +29,7 @@ print(output_json(value))
 print(output_plain(value))
 ```
 
-Useful names use Python casing: `output_json`, `output_yaml`, `output_plain`, `output_json_with_options`, `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `parse_size`, `normalize_utc_offset`, `cli_parse_output`, `cli_output`, and `build_cli_error`.
+Useful names use Python casing: `output_json`, `output_yaml`, `output_plain`, `output_json_with_options`, `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `parse_size`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `cli_parse_output`, `cli_output`, `build_cli_error`, `build_cli_version`, and `cli_handle_version_or_continue`.
 
 Logging is available through `init_logging_json`, `init_logging_plain`, `init_logging_yaml`, `span`, and `get_logger`.
 
@@ -46,6 +46,7 @@ init_logging_json("INFO", secret_names=("authorization",))
 - YAML/plain quote and escape keys as well as values, sort by UTF-16 code unit order, and render nested objects in arrays as canonical JSON.
 - Logging records use `code: "log"` plus a separate `level` field, so error-level logs are not terminal protocol errors.
 - `build_cli_error(message, hint?)` returns `{code:"error", error: message, hint?}` only.
+- Use `cli_handle_version_or_continue()` before argument parsing so bare `--version` stays conventional and `--version --output json|yaml|plain` stays structured.
 
 ## Reference
 

{agent_first_data-0.13.0 → agent_first_data-0.13.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-first-data"
-version = "0.13.0"
+version = "0.13.2"
 description = "A naming convention that lets AI agents understand your data without being told what it means."
 license = "MIT"
 readme = "README.md"

{agent_first_data-0.13.0 → agent_first_data-0.13.2}/tests/test_cli.py

@@ -9,6 +9,9 @@ from agent_first_data import (
     cli_output,
     cli_output_with_options,
     build_cli_error,
+    build_cli_version,
+    cli_render_version,
+    cli_handle_version_or_continue,
     output_json,
 )
 
@@ -120,3 +123,51 @@ def test_cli_output_with_options_dispatches_raw_yaml():
     )
     assert "size_bytes: 1024" in out
     assert "size:" not in out
+
+
+# ── version helpers ───────────────────────────────────────────────────────────
+
+def test_build_cli_version_standard_shape():
+    v = build_cli_version("1.2.3")
+    assert v["code"] == "version"
+    assert v["version"] == "1.2.3"
+    assert "trace" not in v
+
+
+def test_cli_render_version_is_conventional_by_default():
+    assert cli_render_version("agent-cli", "1.2.3") == "agent-cli 1.2.3\n"
+
+
+def test_cli_render_version_can_render_json():
+    out = cli_render_version("agent-cli", "1.2.3", OutputFormat.JSON)
+    assert out.endswith("\n")
+    assert '"code":"version"' in out
+    assert '"version":"1.2.3"' in out
+
+
+def test_cli_handle_version_is_conventional_by_default():
+    assert cli_handle_version_or_continue(["--version"], "agent-cli", "1.2.3") == "agent-cli 1.2.3\n"
+
+
+def test_cli_handle_version_honors_output_flag():
+    out = cli_handle_version_or_continue(
+        ["--version", "--output", "plain"],
+        "agent-cli",
+        "1.2.3",
+    )
+    assert out is not None
+    assert "code=version" in out
+    assert "version=1.2.3" in out
+
+
+def test_cli_handle_version_returns_none_without_version():
+    assert cli_handle_version_or_continue(["ping"], "agent-cli", "1.2.3") is None
+
+
+def test_cli_handle_version_rejects_invalid_output():
+    with pytest.raises(ValueError, match="xml"):
+        cli_handle_version_or_continue(
+            ["--version", "--output", "xml"],
+            "agent-cli",
+            "1.2.3",
+        )

{agent_first_data-0.13.0 → agent_first_data-0.13.2}/tests/test_format.py

@@ -25,6 +25,8 @@ from agent_first_data import (
     output_plain,
     output_plain_with_options,
     normalize_utc_offset,
+    is_valid_rfc3339_date,
+    is_valid_rfc3339_time,
 )
 from agent_first_data.format import (
     _format_bytes_human,
@@ -149,6 +151,12 @@ def test_helper_fixtures():
             elif name == "normalize_utc_offset":
                 got = normalize_utc_offset(inp)
                 assert got == expected, f"[helpers/{name}({inp!r})] got {got!r}"
+            elif name == "is_valid_rfc3339_date":
+                got = is_valid_rfc3339_date(inp)
+                assert got == expected, f"[helpers/{name}({inp!r})] got {got!r}"
+            elif name == "is_valid_rfc3339_time":
+                got = is_valid_rfc3339_time(inp)
+                assert got == expected, f"[helpers/{name}({inp!r})] got {got!r}"
 
 
 def test_output_format_fixtures():