Add API for TOML spec version detection

This adds new functions `loads_with_info()` and `load_with_info()` that
return a `ParseResult` containing:
- `data`: The parsed TOML data (same as before)
- `spec_version`: Minimum TOML spec version required ("1.0" or "1.1")
- `features`: Set of TOML 1.1 features used in the document

Currently detects the `\e` escape sequence (merged in PR hukkin#201) as a
TOML 1.1 feature. TODO comments mark where detection should be added
for pending TOML 1.1 features:
- `\xHH` hex escape (PR hukkin#202)
- Newlines/trailing commas in inline tables (PR hukkin#200)
- Optional seconds in datetime/time (PR hukkin#203)

The existing `loads()` and `load()` functions remain unchanged for
backward compatibility.

New public exports:
- `loads_with_info()`, `load_with_info()`: Parse with version info
- `ParseResult`: Frozen dataclass with parsing results
- `TOMLFeature`: Constants for TOML 1.1 feature identifiers

Addresses: hukkin#273

Author: claude

src/tomli/__init__.py

@@ -2,7 +2,23 @@
 # SPDX-FileCopyrightText: 2021 Taneli Hukkinen
 # Licensed to PSF under a Contributor Agreement.
 
-__all__ = ("loads", "load", "TOMLDecodeError")
+__all__ = (
+    "loads",
+    "load",
+    "loads_with_info",
+    "load_with_info",
+    "TOMLDecodeError",
+    "ParseResult",
+    "TOMLFeature",
+)
 __version__ = "2.3.0"  # DO NOT EDIT THIS LINE MANUALLY. LET bump2version UTILITY DO IT
 
-from ._parser import TOMLDecodeError, load, loads
+from ._parser import (
+    TOMLDecodeError,
+    load,
+    load_with_info,
+    loads,
+    loads_with_info,
+    ParseResult,
+    TOMLFeature,
+)

src/tomli/_parser.py

@@ -4,6 +4,7 @@
 
 from __future__ import annotations
 
+from dataclasses import dataclass
 import sys
 from types import MappingProxyType
 
@@ -23,6 +24,57 @@
 
     from ._types import Key, ParseFloat, Pos
 
+
+class TOMLFeature:
+    """Constants for TOML 1.1 features.
+
+    These identify specific features that require TOML 1.1 spec compliance.
+    """
+
+    ESCAPE_CHAR = "escape_char"  # \e escape sequence
+    HEX_ESCAPE = "hex_escape"  # \xHH escape sequence
+    INLINE_TABLE_NEWLINE = "inline_table_newline"  # Newlines in inline tables
+    INLINE_TABLE_TRAILING_COMMA = "inline_table_trailing_comma"  # Trailing comma in inline tables
+    OPTIONAL_SECONDS = "optional_seconds"  # Date-time/time without seconds
+
+
+@dataclass(frozen=True)
+class ParseResult:
+    """Result of parsing a TOML document with version information.
+
+    Attributes:
+        data: The parsed TOML data as a dictionary.
+        spec_version: The minimum TOML spec version required ("1.0" or "1.1").
+        features: Set of TOML 1.1 feature constants that were used.
+    """
+
+    data: dict[str, Any]
+    spec_version: str
+    features: frozenset[str]
+
+
+class VersionContext:
+    """Tracks TOML 1.1 features used during parsing."""
+
+    __slots__ = ("_features",)
+
+    def __init__(self) -> None:
+        self._features: set[str] = set()
+
+    def mark(self, feature: str) -> None:
+        """Mark a 1.1 feature as used."""
+        self._features.add(feature)
+
+    @property
+    def spec_version(self) -> str:
+        """Return the minimum spec version required."""
+        return "1.1" if self._features else "1.0"
+
+    @property
+    def features(self) -> frozenset[str]:
+        """Return the set of 1.1 features used."""
+        return frozenset(self._features)
+
 # Inline tables/arrays are implemented using recursion. Pathologically
 # nested documents cause pure Python to raise RecursionError (which is OK),
 # but mypyc binary wheels will crash unrecoverably (not OK). According to
@@ -146,8 +198,42 @@ def load(__fp: IO[bytes], *, parse_float: ParseFloat = float) -> dict[str, Any]:
     return loads(s, parse_float=parse_float)
 
 
+def load_with_info(__fp: IO[bytes], *, parse_float: ParseFloat = float) -> ParseResult:
+    """Parse TOML from a binary file object with version information.
+
+    Returns a ParseResult containing the parsed data, the minimum
+    TOML spec version required, and the set of TOML 1.1 features used.
+    """
+    b = __fp.read()
+    try:
+        s = b.decode()
+    except AttributeError:
+        raise TypeError(
+            "File must be opened in binary mode, e.g. use `open('foo.toml', 'rb')`"
+        ) from None
+    return loads_with_info(s, parse_float=parse_float)
+
+
 def loads(__s: str, *, parse_float: ParseFloat = float) -> dict[str, Any]:
     """Parse TOML from a string."""
+    return loads_with_info(__s, parse_float=parse_float).data
+
+
+def loads_with_info(__s: str, *, parse_float: ParseFloat = float) -> ParseResult:
+    """Parse TOML from a string with version information.
+
+    Returns a ParseResult containing the parsed data, the minimum
+    TOML spec version required, and the set of TOML 1.1 features used.
+
+    Example:
+        >>> result = loads_with_info('key = "value with \\e escape"')
+        >>> result.data
+        {'key': 'value with \\x1b escape'}
+        >>> result.spec_version
+        '1.1'
+        >>> result.features
+        frozenset({'escape_char'})
+    """
 
     # The spec allows converting "\r\n" to "\n", even in string
     # literals. Let's do so to simplify parsing.
@@ -161,6 +247,7 @@ def loads(__s: str, *, parse_float: ParseFloat = float) -> dict[str, Any]:
     out = Output()
     header: Key = ()
     parse_float = make_safe_parse_float(parse_float)
+    version_ctx = VersionContext()
 
     # Parse one statement at a time
     # (typically means one line in TOML source)
@@ -184,7 +271,7 @@ def loads(__s: str, *, parse_float: ParseFloat = float) -> dict[str, Any]:
             pos += 1
             continue
         if char in KEY_INITIAL_CHARS:
-            pos = key_value_rule(src, pos, out, header, parse_float)
+            pos = key_value_rule(src, pos, out, header, parse_float, version_ctx)
             pos = skip_chars(src, pos, TOML_WS)
         elif char == "[":
             try:
@@ -214,7 +301,11 @@ def loads(__s: str, *, parse_float: ParseFloat = float) -> dict[str, Any]:
             )
         pos += 1
 
-    return out.data.dict
+    return ParseResult(
+        data=out.data.dict,
+        spec_version=version_ctx.spec_version,
+        features=version_ctx.features,
+    )
 
 
 class Flags:
@@ -411,9 +502,14 @@ def create_list_rule(src: str, pos: Pos, out: Output) -> tuple[Pos, Key]:
 
 
 def key_value_rule(
-    src: str, pos: Pos, out: Output, header: Key, parse_float: ParseFloat
+    src: str,
+    pos: Pos,
+    out: Output,
+    header: Key,
+    parse_float: ParseFloat,
+    version_ctx: VersionContext | None = None,
 ) -> Pos:
-    pos, key, value = parse_key_value_pair(src, pos, parse_float, nest_lvl=0)
+    pos, key, value = parse_key_value_pair(src, pos, parse_float, nest_lvl=0, version_ctx=version_ctx)
     key_parent, key_stem = key[:-1], key[-1]
     abs_key_parent = header + key_parent
 
@@ -445,7 +541,11 @@ def key_value_rule(
 
 
 def parse_key_value_pair(
-    src: str, pos: Pos, parse_float: ParseFloat, nest_lvl: int
+    src: str,
+    pos: Pos,
+    parse_float: ParseFloat,
+    nest_lvl: int,
+    version_ctx: VersionContext | None = None,
 ) -> tuple[Pos, Key, Any]:
     pos, key = parse_key(src, pos)
     try:
@@ -456,7 +556,7 @@ def parse_key_value_pair(
         raise TOMLDecodeError("Expected '=' after a key in a key/value pair", src, pos)
     pos += 1
     pos = skip_chars(src, pos, TOML_WS)
-    pos, value = parse_value(src, pos, parse_float, nest_lvl)
+    pos, value = parse_value(src, pos, parse_float, nest_lvl, version_ctx)
     return pos, key, value
 
 
@@ -494,13 +594,19 @@ def parse_key_part(src: str, pos: Pos) -> tuple[Pos, str]:
     raise TOMLDecodeError("Invalid initial character for a key part", src, pos)
 
 
-def parse_one_line_basic_str(src: str, pos: Pos) -> tuple[Pos, str]:
+def parse_one_line_basic_str(
+    src: str, pos: Pos, version_ctx: VersionContext | None = None
+) -> tuple[Pos, str]:
     pos += 1
-    return parse_basic_str(src, pos, multiline=False)
+    return parse_basic_str(src, pos, multiline=False, version_ctx=version_ctx)
 
 
 def parse_array(
-    src: str, pos: Pos, parse_float: ParseFloat, nest_lvl: int
+    src: str,
+    pos: Pos,
+    parse_float: ParseFloat,
+    nest_lvl: int,
+    version_ctx: VersionContext | None = None,
 ) -> tuple[Pos, list[Any]]:
     pos += 1
     array: list[Any] = []
@@ -509,7 +615,7 @@ def parse_array(
     if src.startswith("]", pos):
         return pos + 1, array
     while True:
-        pos, val = parse_value(src, pos, parse_float, nest_lvl)
+        pos, val = parse_value(src, pos, parse_float, nest_lvl, version_ctx)
         array.append(val)
         pos = skip_comments_and_array_ws(src, pos)
 
@@ -526,8 +632,13 @@ def parse_array(
 
 
 def parse_inline_table(
-    src: str, pos: Pos, parse_float: ParseFloat, nest_lvl: int
+    src: str,
+    pos: Pos,
+    parse_float: ParseFloat,
+    nest_lvl: int,
+    version_ctx: VersionContext | None = None,
 ) -> tuple[Pos, dict[str, Any]]:
+    # TODO: Add newlines and trailing comma detection for TOML 1.1 (PR #200)
     pos += 1
     nested_dict = NestedDict()
     flags = Flags()
@@ -536,7 +647,7 @@ def parse_inline_table(
     if src.startswith("}", pos):
         return pos + 1, nested_dict.dict
     while True:
-        pos, key, value = parse_key_value_pair(src, pos, parse_float, nest_lvl)
+        pos, key, value = parse_key_value_pair(src, pos, parse_float, nest_lvl, version_ctx)
         key_parent, key_stem = key[:-1], key[-1]
         if flags.is_(key, Flags.FROZEN):
             raise TOMLDecodeError(f"Cannot mutate immutable namespace {key}", src, pos)
@@ -560,7 +671,11 @@ def parse_inline_table(
 
 
 def parse_basic_str_escape(
-    src: str, pos: Pos, *, multiline: bool = False
+    src: str,
+    pos: Pos,
+    *,
+    multiline: bool = False,
+    version_ctx: VersionContext | None = None,
 ) -> tuple[Pos, str]:
     escape_id = src[pos : pos + 2]
     pos += 2
@@ -582,14 +697,21 @@ def parse_basic_str_escape(
         return parse_hex_char(src, pos, 4)
     if escape_id == "\\U":
         return parse_hex_char(src, pos, 8)
+    # TODO: Add \xHH escape detection for TOML 1.1 (PR #202)
     try:
-        return pos, BASIC_STR_ESCAPE_REPLACEMENTS[escape_id]
+        replacement = BASIC_STR_ESCAPE_REPLACEMENTS[escape_id]
     except KeyError:
         raise TOMLDecodeError("Unescaped '\\' in a string", src, pos) from None
+    # Detect TOML 1.1 escape sequences
+    if escape_id == "\\e" and version_ctx is not None:
+        version_ctx.mark(TOMLFeature.ESCAPE_CHAR)
+    return pos, replacement
 
 
-def parse_basic_str_escape_multiline(src: str, pos: Pos) -> tuple[Pos, str]:
-    return parse_basic_str_escape(src, pos, multiline=True)
+def parse_basic_str_escape_multiline(
+    src: str, pos: Pos, version_ctx: VersionContext | None = None
+) -> tuple[Pos, str]:
+    return parse_basic_str_escape(src, pos, multiline=True, version_ctx=version_ctx)
 
 
 def parse_hex_char(src: str, pos: Pos, hex_len: int) -> tuple[Pos, str]:
@@ -614,7 +736,13 @@ def parse_literal_str(src: str, pos: Pos) -> tuple[Pos, str]:
     return pos + 1, src[start_pos:pos]  # Skip ending apostrophe
 
 
-def parse_multiline_str(src: str, pos: Pos, *, literal: bool) -> tuple[Pos, str]:
+def parse_multiline_str(
+    src: str,
+    pos: Pos,
+    *,
+    literal: bool,
+    version_ctx: VersionContext | None = None,
+) -> tuple[Pos, str]:
     pos += 3
     if src.startswith("\n", pos):
         pos += 1
@@ -632,7 +760,7 @@ def parse_multiline_str(src: str, pos: Pos, *, literal: bool) -> tuple[Pos, str]
         pos = end_pos + 3
     else:
         delim = '"'
-        pos, result = parse_basic_str(src, pos, multiline=True)
+        pos, result = parse_basic_str(src, pos, multiline=True, version_ctx=version_ctx)
 
     # Add at maximum two extra apostrophes/quotes if the end sequence
     # is 4 or 5 chars long instead of just 3.
@@ -645,13 +773,17 @@ def parse_multiline_str(src: str, pos: Pos, *, literal: bool) -> tuple[Pos, str]
     return pos, result + (delim * 2)
 
 
-def parse_basic_str(src: str, pos: Pos, *, multiline: bool) -> tuple[Pos, str]:
+def parse_basic_str(
+    src: str,
+    pos: Pos,
+    *,
+    multiline: bool,
+    version_ctx: VersionContext | None = None,
+) -> tuple[Pos, str]:
     if multiline:
         error_on = ILLEGAL_MULTILINE_BASIC_STR_CHARS
-        parse_escapes = parse_basic_str_escape_multiline
     else:
         error_on = ILLEGAL_BASIC_STR_CHARS
-        parse_escapes = parse_basic_str_escape
     result = ""
     start_pos = pos
     while True:
@@ -668,7 +800,9 @@ def parse_basic_str(src: str, pos: Pos, *, multiline: bool) -> tuple[Pos, str]:
             continue
         if char == "\\":
             result += src[start_pos:pos]
-            pos, parsed_escape = parse_escapes(src, pos)
+            pos, parsed_escape = parse_basic_str_escape(
+                src, pos, multiline=multiline, version_ctx=version_ctx
+            )
             result += parsed_escape
             start_pos = pos
             continue
@@ -678,7 +812,11 @@ def parse_basic_str(src: str, pos: Pos, *, multiline: bool) -> tuple[Pos, str]:
 
 
 def parse_value(
-    src: str, pos: Pos, parse_float: ParseFloat, nest_lvl: int
+    src: str,
+    pos: Pos,
+    parse_float: ParseFloat,
+    nest_lvl: int,
+    version_ctx: VersionContext | None = None,
 ) -> tuple[Pos, Any]:
     if nest_lvl > MAX_INLINE_NESTING:
         # Pure Python should have raised RecursionError already.
@@ -698,8 +836,8 @@ def parse_value(
     # Basic strings
     if char == '"':
         if src.startswith('"""', pos):
-            return parse_multiline_str(src, pos, literal=False)
-        return parse_one_line_basic_str(src, pos)
+            return parse_multiline_str(src, pos, literal=False, version_ctx=version_ctx)
+        return parse_one_line_basic_str(src, pos, version_ctx=version_ctx)
 
     # Literal strings
     if char == "'":
@@ -717,13 +855,14 @@ def parse_value(
 
     # Arrays
     if char == "[":
-        return parse_array(src, pos, parse_float, nest_lvl + 1)
+        return parse_array(src, pos, parse_float, nest_lvl + 1, version_ctx)
 
     # Inline tables
     if char == "{":
-        return parse_inline_table(src, pos, parse_float, nest_lvl + 1)
+        return parse_inline_table(src, pos, parse_float, nest_lvl + 1, version_ctx)
 
     # Dates and times
+    # TODO: Add optional seconds detection for TOML 1.1 (PR #203)
     datetime_match = RE_DATETIME.match(src, pos)
     if datetime_match:
         try: